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PREFACE 



MAHDAL OBJECTIVES 

This manual describes the concepts and capabilities of the 
RSX-llM/M-PLUS Task Builder. 

Working examples are used throughout this manual to introduce and 
describe features of the Task Builder. Because RSX-llM systems 
support a large number of programming languages, it is not practical 
to illustrate the Task Builder features in all of the languages 
supported. Instead, most of the examples in the main text of this 
manual are written in MACRO-11. 



IHTEKDED AUDIENCE 

Before reading this manual, you should be familiar with the 
fundamental concepts of your operating system (RSX-llM or 
RSX-llM-PLDS) and with the operating procedures described in the 
RSX-llM/M-PLUS MCR Operations Manual . In addition, you should be 
familiar with the programming concepts described in the RSX-llM/M-PLUS 
Guide to Program Development. 



STRUCTDRE OF THIS DOCOMENT 

This manual has 11 chapters. Their contents are summarized as 
follows: 

• Chapter 1 describes the Task Builder command sequences that 
you use to interact with the Task Builder. 

• Chapter 2 describes the basic Task Builder functions, 
including the Task Builder's allocation of virtual address 
space and the resolution of global symbols. It also contains 
an introduction to supervisor-mode libraries, privileged 
tasks, and multiuser tasks. 

• Chapter 3 describes the Task Builder's overlay capability and 
the language you use to define an overlay structure. 

• Chapter 4 describes the two methods available to you to load 
overlay segments. 

• Chapter 5 describes some typical Task Builder features, 
including tasks that access shared regions and device commons, 
tasks that create dynamic regions, and virtual program 
sections . 
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• Chapter 6 defines privileged tasks, describes their mapping, 
and shows how to build a privileged task to examine unit 
control blocks. 

• Chapter 7 describes user-mode I- and D-space, the mapping of 
these spaces, and the advantages of using I- and D-space in 
user mode. 

• Chapter 8 describes supervisor-mode libraries. The chapter 
defines and shows how to build and use supervisor-mode 
libraries. 

• Chapter 9 describes and shows how to build multiuser tasks. 

• Chapter 10 lists and describes the Task Builder switches. The 
switches are listed in alphabetical order. 

• Chapter 11 lists and describes the Task Builder options. The 
options are listed in alphabetical order. 

This manual also contains eight appendices. Their contents are 
summarized as follows: 

• Appendix A contains a detailed description of the Task Builder 
input data structures. 

• Appendix B contains a detailed description of the task image 
file structure. 

• Appendix C describes the considerations for building a task on 
one system to run on a system with a different hardware 
configuration. 

• Appendix D describes two memory dumps: postmortem and 
snapshot. 

• Appendix E contains a list of the symbols and program section 
names reserved for Task Builder use. 

• Appendix F contains information on improving Task Builder 
performance. 

• Appendix G describes the fast Task Builder. 

• Appendix H contains the Task Builder error messages. 
A Task Builder glossary follows the appendices. 



ASSOCIATED DOCUMENTS 

Other manuals closely allied with this document are described in the 
Information Directory and Master Index for your operating system. 
This directory defines the intended audience of each manual in the 
documentation set and provides a brief synopsis of each manual's 
contents. 
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COKVENTIONS DSED IN THIS DOCOMENT 

In this manual, horizontal ellipses (...) indicate that additional, 
optional arguments in a statement format have been omitted. For 
example: 

input-spec , . . . 

means that one or more input-spec items, separated by commas, can be 
specified . 

Vertical ellipses mean that lines in an example, command lines, or 
lines in a Task Builder map file that are not pertinent to an exam.ple 
have been omitted. For example: 

TKB>input-line 



means that one or more of the indicated TKB items have been omitted. 

The words "Task Builder" in this manual have been abbreviated to the 
acronym TKB. 

Unless otherwise stated, references to tasks, their mapping, and their 
structure imply a nonprivileged task in an RSX-llM mapped system. 

In the examples of Task Builder command sequences, the portion of the 
command sequence that you type is printed in red. The Task Builder's 
responses and prompts are printed in black. 

Shading in the manual has the following meanings: 

pink Indicates that the text describes features appearing only 
on RSX-llM operating systems. 

gray Indicates that the text describes features appearing only 
on RSX-1 1 M-Pr.tlS ooer-itina systems. 
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SUMMARY OF TECHNICAL CHANGES 



This manual contains the changes for RSX-llM Version 4.1 and 
RSX-llM-PLUS Version 2.1. This manual has been extensively revised. 
A study of the Table of Contents and this Summary of Technical Changes 
is recommended before you look for information in the manual. 



GENERAL CHANGES 

Editorial changes were made throughout the manual to correct 
typographical errors. 

Small technical changes were made throughout the manual as a result of 
ongoing development, SPR responses, and readers' comments. 

The major technical changes to the manual are listed below. 



TECHNICAL CHANGES 
NEW OPTIONS 

DSPPAT — Allows object-level patching of a conventional task or 

the- O^space' -ptact ,of; art- 1-„ .and; fx-spape;, ta-sk-„ 

CHANGED OPTIONS 

ABSPAT — Allows object-level patching of a conventional task or 

COMMON — The COMMON option causes the common to be mapped with 
D-space APRS. Therefore, for I- and n-space tasks, the common^ 
can contain data only. 

EXTTSK — Extends the D-space portion of an I- and D-space task. 
Because libraries are mapped with both I-space APRS and D-space 
APRS, extending the D-space of I- and D-space tasks may cause 
unmapping of the library's D-space APRs, which causes the library 
to be mapped in I-space only. 

LIBR — The LIBR option causes the library to be mapped with both 
I-space and D-space APRs when linked to an i- and D-space task. 

RKSCOM — The RESCOM option causes the common to be mapped with 
D- space APRS. Therefore, for I- and D-space tasks, the common 
can contain data only, 

RESLIB — The RESLTB option causes the library to hp mapped with 
both I-space and D-space APRs when linked to an I- and D-space 
task . 
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SUMMARY OF TECHNICAL CHANGES 

NEW ERROR MESSAGES 

Module module-name contains incompatible autoload vectors 

CHANGED ERROR MESSAGES 

Lookup failure resident library file 

changed to 
Lookup failure resident library file - filename. ext 

MISCELLANEOUS TECHNICAL CHANGES 

Autoload vectors for conventional tasks have changed. The call 
to $AUTO is now made indirectly through .NAUTO in the overlay 
impure area. 

I- and D-space tasks may be overlaid by using either autoload, or 
manual load . ' . ■ " 

Autoload vectors for I- and D-space tasks have a format, different 
from those of conventional tasks. The autoload vectors for I- 
and D-space tasks contain an I-space part located in the task's 
1-space and a D-space part located in the task's D-space. 

Memory allocation diagrams may be used as an aid to create .ODL 
files . 

Overlay Run-time System routines have changed size from the 
previous release. 

MACRO-11 and FORTRAN manual load calling sequences for overlays 
in I- and D-space tasks may not use asynchronous loading. 

For versions of TKB that support I- and D-space tasks and that 

were used to build libraries, TKB allocates autoload vectors in 

the root of the task only for those autoloadable entry points in 
the library referenced by the task. 

I- and D-space tasks may link to commons, conventional libraries, 
and supervisor-mode libraries. 

Loading I- and D-space tasks into memory requires two disk 
accesses. Overlaid I- and D-space tasks may require, in 
addition, two disk accesses for loading each segment if the 
segment contains both l-space and D-space. 

Segment descriptors for I- and D-space tasks contain an extension 
for the D-space part. 

Only one level of overlay is allowed in supervisor-mode 
1 ibrar ies . 

I- and D-space multiuser tasks are allowed, TKB uses four window 
blocks to map these tasks. 

Internal Symbol Directory Records, along with their formats, are 
described in Appendix A. They consist of: 

• Type 1 records, generated by TKB and output to the .STB file 

• Type 2 records, generated by language processors 



SUMMARY OF TECHNICAL CHANGES 

• Type 3 records, created from type 2 records and output to the 
.STB file 

• Type 4 records, written to the .STB file without modification 

A new bit called LD$TYP distinguishes between a library or common. 
See offset R$LFLG in the resident library name block data in Appendix 
B. 

The first library in a cluster may be overlaid and contain a non-null 
root. 

New Task Builder reserved symbols have been added to Appendix E. 

The Fast Task Builder supports the /EA switch and the TASK= option. 

The map format for an I- /and. 0-space task , shows both I^^^ 
contributions to a segment /a n^a 'tlie^'dtsfc BlpcksVthat\'COHtal;h' aa-tan 
sections. 

Other minor technical and editorial changes have been made also. 
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CHAPTER 1 
INTRODUCTION AND COMMAND SPECIFICATIONS 

The basic steps in developing a program are as follows: 

1. You write one or more routines in an RSX-llM/M-PLUS supported 
source language and enter each routine as an ASCII text file, 
through an editor. 

2. You submit each text file to the appropriate language 
translator (an assembler or compiler) , which converts it to a 
relocatable object module. 

3. You specify the object modules as input to the Task Builder 
(TKB) , which combines the object modules into a single task 
image output file. 

4. You install and run the task. 

If you find errors in the task when you run it, you make corrections 
to the text file using the editor, and then repeat steps 2 through 4. 

The Task Builder's main function is to convert relocatable object 
modules (.OBJ files) into a single task image (.TSK file) that you can 
install and run on a RSX-llM or RSX-llM-PLUS system. The task is the 
fundamental executable unit in both systems. 

If your program consists of a single object module, using the Task 
Builder (TKB) is appropriately simple. You specify as input only the 
name of the file containing the object module produced from the 
translation of the program, and specify as output the task image file. 

Typically, however, programs consist of more than a single object 
module. In this case, you name each of the object module files as 
input. TKB links the object modules, resolves references between 
them, resolves references to the system library, and produces a single 
task image ready to be installed and executed. 

TKB makes a set of assumptions (defaults) about the task image based 

on typical usage and storage requirements. You can override these 

assumptions by including switches and options in the task-building 

terminal sequence. Thus, you can build a task that is tailored to its 
own input/output and storage requirements. 

TKB also produces (upon request) a memory allocation (map) file that 
contains information describing the allocation of address space, the 
modules that make up the task image, and the value of all global 
symbols. In addition, you can request that a list of global symbols, 
accompanied by the name of each referencing module, be appended to the 
file (global cross reference) . 
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INTRODUCTION AND COMMAND SPECIFICATIONS 

Note that the examples in this manual use MCR as the operating system 
language. Refer to the RSX-llM-PLUS Command Language Manual and, in 
particular, to the command in that manual for DIGITAL Command Language 
equivalence . 

The following example shows a simple sequence for building a task: 

>MAC PROG=PROG 

>TKB PROG=PROG 

>INS PROG 

>RUN PROG 

The first command (MAC) causes the MACRO-11 assembler to translate the 
source code of the file PROG. MAC into a relocatable object module in 
the file PROG. OBJ. The second command (TKB) causes TKB to process the 
file PROG. OBJ and to produce the task image file PROG.TSK. The third 
command (INS) causes the INSTALL processor to add the task to the 
Executive's directory of executable tasks (System Task Directory). 
The fourth command (RUN) causes the task to execute. 

The example just given includes the command 

>TKB PROG=PROG 

This command illustrates the simplest use , of TKB. It gives the name 
of a single file as output and the name of a single file as input. 

The following sections describe basic Task Builder command forms and 
sequences . 



1.1 TASK COMMAND LINE 

The task command line contains the output file specifications, 
followed by the input file specifications; they are separated by an 
equal sign (=) . You can specify up to three output files and any 
number of input files. 

The task command line has the following form: 

task-image-file, map-file, symbol-definition-file=input-file, . . . 

You must give the output files in a specific order: the first file 
you name is the image (.TSK) file; the second is the memory 
allocation (.MAP) file; and the third is the symbol definition (.STB) 
file. The map file lists information about the size and location of 
components within the task. The symbol definition file contains the 
global symbol definitions in the task and their virtual or relocatable 
addresses in a format suitable for reprocessing by TKB. You specify 
this file when you are building a resident library or common. 
(Resident libraries and commons are described in Chapter 3.) TKB 
combines the input files to create a single task image that can be 
installed and executed. 



1.1.1 Printing the Map File 

If you create a map file by specifying one in the TKB command line, 
there are a number of ways that you can print the file. The following 
examples show you ways that you may print the map file. 

1. With the following two command lines, you can create a map 
file and then print it later. The TKB command line tells TKB 
to create a task file, a map file without printing it (by use 
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of the switch /-SP) , and a symbol definition file. The PRINT 
command line tells the system to print the map file. 

>TKB INV.TSK,INV.MAP/-SP,INV.STB=INV.OBJ 
>PRINT INV.MAP 

With the next command line, you can print the map file 
directly as it is created. In this case, TKB tells the 
system to print the file by use of the switch /SP. However, 
the system task PRT... or ...PRT must be installed for this 
method to work. 



>TKB INV.TSK,INV.MAP/SP,INV.STB=INV.OBJ 



With the next command line, you can print the map file on a 
line printer that you specify. It is best to use this 
command line on an RSX-llM-PLUS system because that system 
uses transparent spooling. Using this command line on an 
RSX-llM system may cause the printer to be unavailable to 
other tasks. See your system manager for specific details 
about using the following command line. 

>TKB INV.TSK,LPn: ,SY:INV.STB=INV.OBJ 



1.1.2 Omitting Specific Output Files 

You can omit any output file by replacing the file specification with 
the delimiting comma that would normally follow it. The following 
commands illustrate the ways in which TKB interprets the output file 
names. 



Command 



Output Files 



>TKB IMG1,IMG1,IMG1=IN1 The task image file is IMGl.TSK, the 

memory allocation (map) file is 
IMGl.MAP, and the symbol definition file 
is IMGl.STB. 



>TKB IMG1=IN1 

>TKB ,IMG1=IN1 
>TKB ,,IMG1=IN1 

>TKB IMG1,,IMG1=IN1 

>TKB =IN1 



The task image file is IMGl.TSK. 

The map file is IMGl.MAP. 

The symbol definition file is IMGl.STB. 

The task image file is IMGl.TSK and the 
symbol definition file is IMGl.STB. 

This is a diagnostic run with no output 
files. 



1.2 MOLTILINE INPUT 

Although you can specify a maximum of three output files, you can 
specify any number of input files. When you specify several input 
files, a more flexible format is sometimes necessary — one that 
consists of several lines. This multiline format is also necessary 
when you want to include options in your command sequence (see Section 
1.3) . 
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If you type TKB, the Monitor Console Routine (MCR) activates the Task 

Builder. TKB then prompts for input until it receives a line 

consisting only of the terminating slash characters (//) . For 
example: 

>TKB 

TKB>IMG1,IMG1=IN1 
TKB>IN2,IN3 
TKB> // 

This sequence produces the same result as the single line command 

>TKB IMG1,IMG1=IN1,IN2,IN3 

Both command sequences produce the task image file IMGl.TSK and the 
map file IMGl.MAP from the input files INI. OBJ, IN2.0BJ, and IN3.0BJ. 

you must specify the output file specifications and the equal sign (=) 
on the first command line. You can begin or continue input file 
specifications on subsequent lines. 

When you type the terminating slash characters (//) , TKB stops 
accepting input, builds the task, and returns control to MCR, 



1.3 OPTIONS 

You use options to specify the characteristics of the task you are 
building. To include options in a task, you must use the multiline 
format. If you type a single slash (/) following the input file 
specification, TKB requests option information by displaying ENTER 
OPTIONS: and prompting for input. For example: 

>TKB 

TKB>IMG1,IMG1=IN1 

TKB>IN2,IN3 

TKB/ 

Enter Options: 

TKB>pRi=i00 

TKB> COMMON= JRNAL : RO 

TKB>// 

In this sequence there are two options: PRI=100 and COMMON=JRNAL: RO. 
The two slashes end option input, initiate the task build, and return 
control to MCR upon completion. 

NOTE 

When you are building an overlaid task, 
there are exceptions to the use of the 
single slash (/) . Overlaid tasks are 
described in Chapter 4. 

The RSX-llM/M-PLUS Task Builder provides numerous options, which are 
described in Chapter 11. The general form of an option is a keyword 
followed by an equal sign (=) and an argument list. The arguments in 
the list are separated from one another by a colon {:). In the 
example above, the first option consists of the keyword PRI and a 
single argument indicating that the task is to be assigned the 
priority 100. The second option consists of the keyword COMMON and an 
argument list, JRNAL:RO, indicating that the task accesses a resident 
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common region named JRNAL and that the access is read-only. You can 
specify more than one option on a line by using an exclamation point 
(!) to separate the options. For example, the command 

TKB> PRI = 100 ! COMMON= JRNAL : RO 

is equivalent to the two lines: 

TKB>PRI=100 

TKB> COMMON= JRNAL : RO 

Some options accept more than one set of argument lists. You use a 
comma (,) to separate the argument lists. For exam.ple, in the command 

TKB> COMMON= JRNAL : RO , RF IL : RW 

the first argument list indicates that the task has requested 

read-only access to the resident common JRNAL. The second argument 

list indicates that the task has requested read/write access to the 
resident common RFIL. 

The following three sequences are equivalent: 

TKB>COMMON= JRNAL :R0, RFIL :RW 

TKB> C0MM0N= JRNAL : RO ! C0MM0N=RF IL : RW 

TKB> COMMON= JRNAL : RO 
TKB>COMMON=RFIL:RW 



1.4 MULTIPLE TASK SPECIFICATIONS 

If you intend to build more than one task, you can use the single 

slash (/) following option input. This directs TKB to stop accepting 

input, build the task, and request information for the next task 
build. For example: 

>TKB 

TKB>IMG1=IN1 

TKB> IN2,IN3 

TKB>/ 

Enter Options: 

TKB>PRI=100 

TKB> COMMON= JRNAL : RO 

TKB>/ 

TKB> IMG2=SUB1 

TKB> // 

TKB accepts the output and input file specifications and the option 
input; it then stops accepting input upon encountering the single 
slash {/) during option input. TKB builds IMGl.TSK and then returns 
to accept more input for building IMG2.TSK. 



1.5 INDIRECT COMMAND FILES 

You can enter commands to TKB directly from the keyboard, or 
indirectly through the indirect command file facility. To use the 
indirect command file facility, you prepare a file that contains the 
TKB commands you want to be executed. Later, after you invoke TKB, 
you type an at sign (@) followed by the name of the indirect command 
file. 
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For example, suppose you create a file called AFIL.CMD containing the 
following: 

IMG1,IMG1=IN1 
IN2,1N3 

/ 

PRI=100 

COMMON=JRNAL:RO 

// 

Later, you can type: 

>TKB 

TKB>@AFIL 

TKB> 

or simply: 

>TKB @AFIL 

When TKB encounters the at sign (@) , it directs its search for 
commands to the file named AFIL.CMD. The example above is equivalent 
to the keyboard sequence 

>TKB 

TKB>IMG1,IMG1=IN1 

TKB>IN2,IN3 

TKB>/ 

Enter Options: 

TKB>PRI=100 

TKB>COMMON= JRNAL : RO 

TKB>// 

When TKB encounters two terminating slash characters (//) in the 
indirect command file, it terminates indirect command file processing, 
builds the task, and exits to MCR. 

When TKB encounters a single slash (/) in an indirect command file and 
the slash is the last character in the file, TKB directs its search 
for commands to the terminal. For example, suppose the file AFIL.CMD 
in the last example is changed to read: 

IMG1,IMG1=IN1 

IN2,IN3 

/ 

Later, you can type: 

>TKB 
TKB>@AFIL 

In this case, TKB goes to the terminal and prompts: 

Enter Options: 

TKB> 

From this point, you input options to TKB directly from the keyboard. 
If you then conclude option input from the keyboard with double 
slashes (//) , TKB suspends command processing, as described above, and 
exits to MCR following the task build. If you conclude option input 
with a single slash (/) , TKB prompts for new command input following 
the task build of IMGl.TSK, as follows: 

TKB> 
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Using the single slash (/) following option input in indirect command 
files is a convenient way to return control to your terminal between 
successive task builds. For example, suppose you create two indirect 
command files. The first, AFIL.CMD, contains: 

IMG1,IMG1=IN1 

IN2,IN3 

/ 

PRI=100 

COMMON=JRNAL 
/ 

The second, AFIL1.CMD, contains: 

IMG2,IMG2=IN4 

IN5,IN6 

/ 

PRI=100 

// 

Then, the terminal sequence to build these two tasks is: 

>TKB 

TKB>@AFIL 
TKB>@AFIL1 
> 



NOTE 

For interaction with a TKB indirect 
command file as described above, you 
must use the multiline format when you 
specify the indirect command file. 

TKB permits two levels of indirection in file references. That is, 
the indirect command file referenced in a terminal sequence can 
contain a reference to another indirect command file. For example, if 
the file BFIL.CMD contains all the standard options that are used by a 
particular group of users at an installation, you can modify AFIL to 
include an indirect command file reference to BFIL.CMD as a separate 
line in the option sequence. 

The contents of AFIL.CMD would then be: 

IMG1,IMG1=IN1 

IN2,IN3 

/ 

PRI=100 

COMMON=JRNAL:RO 

@BFIL 

// 

To build these files, you type: 

>TKB 

TKB> OAFIL 

Suppose the contents of BFIL.CMD are: 

STACK=100 
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Then the terminal equivalent of building these files is: 

>TKB 

TKB>IMG1,IMG1=IN1 

TKB>IN2,IN3 

TKB>/ 

Enter Options: 

TKB>PRI=100 

T KB > COMMON= J RN AL : RO 

TKB>STACK=100 

TKB>UNITS=5 ! ASG=DT1 : 5 

TKB>// 

The indirect command file reference must appear on a separate line. 

For example, if you modify AFIL.CMD by adding the @BFIL reference on 

the same line as the COMMON=JRNAL:RO option, the substitution would 

not take place and TKB would report an error. 



1.6 COMMENTS IN LINES 

You can include comments at any point in the command sequence, except 
in lines that contain file specifications. You begin a comment with a 
semicolon (;) and terminate it with a carriage return. All text 
between these delimiters is a comment. 

For example, in the indirect command file AFIL.CMD, described in 
Section 1.5, you can add comments to provide more information about 
the purpose and the status of the task. 

TASK 33A 

DATA FROM GROUP E-46 WEEKLY 
IMG1,IMG1= 

PROCESSING ROUTINES 
Nl 

STATISTICAL TABLES 
IN2 

ADDITIONAL CONTROLS 

IN3 

/ 
PRI=100 

COMMON=JRNAL:RO ; RATE TABLES 

; TASK STILL IN DEVELOPMENT 

f 

// 

1.7 FILE SPECIFICATIONS 

TKB adheres to the standard RSX-llM/M-PLUS conventions for file 
specifications. For any file, you can specify the device, the User 
File Directory (UFD) , the file name, the file type, the file version 
number, and any number of switches. 



1-8 



IHTRODOCTION AND COMMAND SPECIFICATIONS 

The file specification has the form 

device: [group, member] f ilename. type; vers ion/swl/sw2. . ./swn 

When you specify files by name only, TKB applies the default switch 
settings for device, group, member, type, and version. 

For example: 

>TKB 

TKB>IMG1,IMG1=IN1 
TKB>IN2,IN3 
TKB>// 

If the current User Identification Code (UIC) of the terminal that TKB 
is running on is [200,200], the task image file specification of the 
example is assumed to be: 

SYO: [200,200] IMG1.TSK;1 

That is, TKB creates the task image file on the system device (SYO:) 
under UFD [200,200] , The default type for a task image file is .TSK 
and, if the name IMGl.TSK is new, the version number is 1. The 
default settings for all the task image switches also apply. Switch 
defaults are described in detail in Chapter 6. 

For example: 

>TKB 

TKB> [ [20,23] ]IMG1/CP/DA,IMG1/CR=IN1 

TKB>IN2;3,IN3 

TKB>// 

This sequence of commands instructs TKB to create a task image file 
IMGl.TSK; 1 and a memory allocation (map) file IMGl.MAP;! (actually, it 
produces IMGl.TSK and IMGl.MAP with versions one higher than the 
current versions) under UFD [20,23] on the device SY:. The task image 
is checkpointable and contains the standard debugging aid (ODT) . TKB 
outputs the map to the line printer with a global cross-reference 
listing appended to it. TKB builds the task from the latest versions 
of INI. OBJ and IN3.0BJ, and the specific version of IN2.0BJ. The 
input files are all found on the system device. 

The system device (SY:) is always the default device unless you 
specify otherwise. If you specify another device on either side of 
the equal sign, that device becomes the default device for the files 
on that side of the equal sign. For example: 

>TKB 

TKB> [ [20,23] ] IMG1,IMG1,IMG1=DB1:IMG1,IN1,IN2 

This command line produces a task image file, map file, and listing 
file in UFD [20,23] on device SY:. All the object files are in UFD 
[20,23] on device DBl. In cases where files are scattered among 
several devices, the devices must be specified in the command line. 

For some files, a device specification is sufficient. In the example 
above, the map file could be fully specified by the device LP:. The 
map listing is produced on the line printer, but is not retained as a 
file. 

This example also used switches /CP, /CR, and /DA, The code, syntax, 
and meaning for each switch are given in Chapter 6. 



1-9 



INTRODDCTION AND COMMAND SPECIFICATIONS 

1.8 SUMMARY OF SYNTAX ROLES 

The syntax rules for issuing commands to TKB are as follows: 

• A task-build command can take any one of four forms. The 
first form is a single line: 

>TKB task-command-line 

The second form has additional lines for input file names: 

>TKB 

TKB>task-command-line 

TKB>input-line 

TKB >termina ting-symbol 
The third form allows you to specify options: 

>TKB 

TKB >task-command- line 

TKB>/ 

Enter Options: 

TKB>opt ion- line 

TKB>terminating-symbol 

The fourth form has both input lines and option lines: 

>TKB 

TKB>task-command-line 

TKB>input-line 



TKB>/ 

Enter Options: 

TKB >opt ion- line 



TKB >termina ting -symbol 
The terminating symbol can be: 

/ if you intend to build more than one task 

// if you want TKB to return control to MCR 
A task command line has one of the three forms: 

output-f ile-1 is t= input-file, 

=input-f ile, . . . 

@ indirect-command- file 

The third form is an indirect command file specification, as 
described in Section 1.5. 
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An output file list has one of the three forms: 

task-image-f lie, map- file, symbol-defi nit ion-file 

task- image- file, map- file 

task-image-f ile 

The task-image-file is the file specification for the task 
image file; map-file is the file specification for the memory 
allocation (map) file; and symbol-definition-file is the file 
specification for the symbol definition file. Any of the 
specf ications can be omitted, so that, for example, the 
following form is permitted: 

task-image-f ile, ,symbol-defi nit ion- file 

An input line has one of two forms: 

input-file, . . . 

@ indirect-command- file 

Both input-file and indirect-command-file are file 
specifications. 

An option line has one of two forms: 

option! . . . 

@ indirect- command-file 
The indirect-command-file is a file specification. 
An option has the form: 

keyword=argument-list , . . . 
The argument-list is: 

arg: . . . 

The syntax for each option is given in Chapter 6. 

A file specification conforms to standard RSX-IM/M-PLUS 
conventions. It has the form: 

device: [group, member] f ilename.type; version/swl/sw2. . ./swn 

device: 

The name of the physical device on which the volume 
containing the desired file is mounted. The name consists 
of two ASCII characters followed by an optional 1- or 
2-digit octal unit number and a colon; for example, LP: 
or DTI:. 

group 

The group number, in the range of 1 through 377(8). 



1-11 



INTRODUCTION AND COMMAND SPECIFICATIONS 

member 

The member number, in the range 1 through 377(8). 

filename 

The name of the desired file. The file name can contain up 
to 9 alphanumeric characters. 



type 



The 3-character file type identification. Files having the 
same name but a different function are distinguished from 
one another by the file type; for example, CALC.TSK and 
CALC.OBJ. 



version 



The version number, in octal, of the file. Various 
versions of the same file are distinguished from one 
another by this number; for example, CALC.0BJ;1 and 
CALC.OBJ; 2. 

All components of a file specification are optional. The 
combination of the group number and the member number is 
the User File Directory (UFD) that contains the file name. 
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CHAPTER 2 
TASK BUILDER FUNCTIONS 



The process of building a task involves three distinct Task Builder 
(TKB) functions: 

1. Linking object modules 

2. Assigning addresses to the task image 

3. Building data structures into the task 

First, TKB is a linker. It collects and links the relocatable object 
modules that you specify to it into a single task image, and resolves 
references to global symbols across the module boundaries. 

Second, TKB assigns addresses to the task image. On mapped systems, 
TKB assigns addresses for a task beginning at 0. The Executive then 
relocates the addresses at run time. On unmapped systems, TKB assigns 
addresses for a task beginning at the base address of the partition in 
which the task is to run. The addresses of tasks that run on unmapped 
systems are not relocated at run time. 

NOTE 

Unless otherwise indicated, references 
to tasks that run on mapped systems 
assume that the tasks are nonpr ivileged 
and residing within system-controlled 
partitions. 

Third, TKB builds data structures into the task image that are 
required by the INSTALL processor to install the task and by the 
Executive to run it. 

This chapter describes the three TKB functions in detail. It also 
describes the concepts of mapped and unmapped systems. In addition, 
this chapter introduces regions, supervisor-mode libraries, overlays, 
privileged tasks, I- and D-space tasks, and many of the mapping 
concepts necessary for an understanding of task mapping and Task 
Builder functions. 



2.1 LINKING OBJECT MODULES 

TKB links object modules within the context of program sections and 
resolves references to global symbols across module boundaries. 

When the language translators convert symbolic source code within a 
module to object code, they assign provisional 16-bit addresses to the 
code. A single assembly or compilation produces a single object 
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module. In its simplest form, each module begins at and extends 
upward to the highest address in the module. Three object modules 
produced at separate times might have the address limits shown in 
Figure 2-1. 



1000- 



RELOCATABLE 0- 



MODULE #1 



750 



500- 



RELOCATABLEO- 



MODULE #2 



RELOCATABLE 




Figure 2-1 Relocatable Object Modules 



If these modules represent the separate modules of a single program, 
TKB links them together and modifies the provisional addresses to one 
of the following: 

• For a mapped system, a single sequence of addresses beginning 
at and extending upward to the sum of the lengths of all the 
modules (-1 byte) 

• For an unmapped system, a single sequence of addresses 
beginning at a base address assigned at task-build time and 
extending upward to the sum of the lengths of all the modules 
(-1 byte) 



For example. Figure 2-2 shows the three modules linked 
system and the modules linked for an unmapped system. 



for a mapped 



2.1.1 Allocating Program Sections 

The language translators process source code and TKB links object 
modules within the context of program sections. A program section is 
a block of code or data that consists of three elements: 

• A name 

• A set of attributes 

• A length 

A program section is the basic unit used by TKB to determine the 
placement of code and data in a task image. The language translators 
maintain a separate location counter for each program section in a 
program. The name of each program section, its attributes, and its 
length are conveyed to TKB through the object module. 
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2250' 



MODULE #3 



MODULE #2 



MODULE #1 



3250- 



BASE 1000-1 



MODULE #3 



MODULE #2 



MODULE #1 



MAPPED 
SYSTEM 



UNMAPPED 
SYSTEM 



Figure 2-2 Modules Linked for Mapped and Unmapped Systems 



You can create as many program sections with 
explicitly declaring them (with the COMMON s 
.PSECT directive in MACRO-11, for example) o 
translator to create them. If you do not e 
section in your source code, the language tr 
with will create a "blank" program sec 
translated. This program section will appea 
maps as . BLK. . For more information on e 
sections, see your language reference manual 



in a module as you wish by 
tatement in FORTRAN or the 
r by allowing the language 
xplicitly create a program 
anslator you are working 
tion within each module 
r on your listings and 
xplicitly declared program 



A program section's name is the name by which the language translator 
and TKB reference it. When processing files, both the language 
translator and TKB create internal tables that contain program section 
names, attributes, and lengths. A named program section can be 
declared more than once. However, all occurrences of that named 
program section must have identical attributes if the section occurs 
more than once in the sam.e m^odule or if the section is a ^lobal 
program section. Identically named program sections within the same 
module and global program sections with differing attributes cause TKB 
to declare the program section as having multiple attributes, which is 
an error. However, identically named program sections with differing 
attributes may appear in different trees of an overlaid task if the 
program sections have the local (LCL) attribute. 



2-3 



TASK BUILDER FUNCTIONS 



Program section attributes define a program section's contents, its 
placement in a task image, and, in some cases, the allowed mode of 
access (read/write or read-only) . 

A program section's length determines how much address space TKB must 
reserve for it. 

When a program consists of more than one module, it is not unusual for 
program sections of the same name to exist in more than one of the 
modules. Therefore, as TKB scans the object modules, it collects 
scattered occurrences of program sections of the same name and 
combines them into a single area of your task image file. The 
attributes listed in Table 2-1 control the way TKB collects and places 
each program section in the task image. 



Table 2-1 
Program Section Attributes 



Attribute Value 



Meaning 



access-code 



RW Read/write: data can be read from, 
written into, the program section. 



and 



RO Read-only: data can be read from, but 
cannot be written into, the program 
section. 



allocation-code CON 



Concatenate: all references to a given 
program section name are concatenated; 
the total allocation is the sum of the 
individual allocations. 



OVR Overlay: all references to a given 
program section name overlay each other; 
the total allocation is the length of the 
longest individual allocation. 



relocation-code REL 



Relocatable: the base address of the 
program section is relocated relative to 
the base address of the task. 



ABS Absolute: the base address of the 
program section is not relocated; it is 
always 0. 



save 



SAV The program section has the SAVE 
attribute, and TKB forces the program 
section into the root. 



scope-code 



GBL Global: the program section name is 
recognized across overlay segment 
boundaries; TKB allocates storage for 
the program section from references 
outside the defining overlay segment. 



LCL Local: the program section name is 
recognized only within the defining 
overlay segment; TKB allocates storage 
for the program section from references 
within the defining overlay segment only. 

(continued on next page) 
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Table 2-1 (Cont.) 
Program Section Attributes 



Attribute Value 



Meaning 



type-code d 



Data: the program section contains data. 



I Instruction: the program section 
contains either instructions, or data and 
instructions . 



2.1 1.1 Access-code and Allocation-code - TKB uses a proqram 
section s access-code and allocation-code to determine its placement 

tkI ^^f,H^'2/ ^11" '"'^^^- ^^ ^°" specify /SG in the command sequence, 
TKB divides address space into read/write and read-only areas, and 
places tne program sections in the appropriate area according to 
a?phabeticail "°"^''^''' ^^^ default is to order the program sections 

TKB uses a program section's allocation-code to determine its starting 

^^ = f^m^o ^"<3^1^"gth. If a program section's allocation-code indicates 

that TKB IS to overlay it (OVR) , TKB places each allocation to the 

program section from each module at the same address within the task 

"ilnnth ^r^ ^^^''"''"!^ ^^^ ^°^^^ ^^^^ °f the program section from the 
length of the longest allocation to it. 

If a program section's allocation-code indicates that TKB is to 
concatenate it (CON), TKB places the allocation from the modules one 

frll\u^^f I i^ ^^^ ""^t^ '"'^5^' ^"^ determines the total allocation 
from the sum of the lengths of each allocation. 

r^^ir^K ^^^°''^t^^ address space for a program section beginning on 
a word boundary. if the program section has the D (data) and CON 

innn^J?r ^f"''i^"^^^' ""^^ ^PP^"^^ t° ^^^ l^^t byte of the previous 
allocation all storage contributed by subsequent modules. It does 
this regardless of whether that byte is on a word or nonword boundary. 
For a program section with the I (instruction) and CON attributes. 

b^aTnn^;. ^H i^''^''^^ address space contributed by subsequent modules 
beginning with the nearest following word boundary. 

For example, suppose three modules, INI, IN2, and IN3, are to be task 
built. Table 2-2 lists these modules with the program sections that 
each contains and their access codes and allocation codes. 

in this example, the program section named B, with the attribute CON 

(concatenate), occurs twice. Thus, the total allocation for B is the 

sum ot the lengths of each occurrence; that is, 100 + 120 = 220 The 

program section named A also occurs twice. However, it has the OVR 

(overlay) attribute; so its total allocation is the largest of the 
two sizes, or 300. Table 2-3 lists the individual program section 
aiiocations. 
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Table 2-2 
program Sections for Modules INl, IN2 , and IN3 



File Name 


Program 
Section 
Name 


Access 
Code 


Allocation 
Code 


Size 
(Octal) 


INI 


B 

A , 
C 


RW 
RW 
RO 


CON 
OVR 
CON 


100 
300 
150 


IN2 


A 

B 


RW 
RW 


OVR 
CON 


250 
120 


IN3 


C 


RO 


CON 


50 



Table 2-3 
Individual Program Section Allocations 



program Section 
Name 



Total 
Allocation 



B 
A 
C 



220 
300 
220 



TKB then groups the program sections according to their 
and alphabetizes each group, as shown in Figure 2-3. 



access codes 



NOTE 

The example shown in Figure 2-3 
represents the Task Builder's allocation 
of program sections if the /SG or /M 
switches are used. For more 
information, see the description of the 
/MU, /SQ, and /SG switches in Chapter 
10. 



C (220) 



B (220) 



A (300) 



STACK 



HEADER 



] 


READ-ONLY 
ACCESS 




READ/WRITE 
ACCESS 







TASK MEMORY 



ZK-379-81 



Figure 2-3 Allocation of Task Memory 
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The save attribute (SAV) is useful in cases where the information in a 
program section must be kept available to all task segments. The SAV 
attribute of a program section causes TKB to force the program section 
into the root of an overlaid task. Therefore, the named common block 
in the FORTRAN SAVE Statement or the named program section in the 
MACRO-11 .PSECT directive specified with the SAV attribute are in the 
root of the task. 



2.1.1.2 Type-Code and Scope-Code - The scope-code is meaningful only 
when you define an overlay structure for a task. The scope-code is 
described in Chapters 3 and 4 within the context of the descriptions 
of overlays. {The type-code is meaningful in the context of program 
sections within an I- and D-space task, as described in Chapter 7.} 



2.1.2 Resolving Global Symbols 

TKB resolves references to global symbols across module boundaries and 
any references (explicit or implicit) to the system library. When the 
language translators process a text file, they assume that references 
to global symbols within the file are defined in other, separately 
assembled or compiled modules. As TKB links the relocatable object 
modules, it creates an internal table of the global symbols it 
encounters within each module. If, after TKB examines and links all 
the object modules, references remain to symbols that have not been 
defined, TKB assumes that it will find the definition for the symbols 
within the default system object module library (LB: [ 1,1] SYSLIB.OLB) . 
If undefined symbols still remain after SYSLIB is examined, TKB flags 
the symbols as undefined. If you have not specified an output map in 
your TKB command sequence, TKB reports the names of the undefined 
symbols to you on your terminal. If you have specified an output map, 
TKB outputs to your terminal only the fact that the task contains 
undefined symbols. The names of the symbols appear on your map 
listing . 

When creating the task image file, TKB resolves global references, as 
shown in the following example. Table 2-4 lists the three files INI, 
IN2, and IN3, showing the program sections within each file, the 
global symbol definitions within each program section, and the 
references to global symbols in each program section. 

Table 2-4 
Resolution of Global Symbols for INI, IN2, and IN3 



File Program Section Global Global 
Name Name Definition Reference 



INI B Bl A 

B2 LI 

A CI 

XXX 
C 

IN2 A A 

B Bl B2 

IN3 C Bl 
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In processing the first file, INI, TKB finds definitions for Bl and B2 
and references to A, LI, CI, and XXX. Because no definition exists 
for these references, TKB defers the resolution of these global 
symbols. In processing the next file, IN2, TKB finds a definition for 
A, which resolves the previous reference, and a reference to B2 , which 
can be immediately resolved. 

When all the object files have been processed, TKB has three 
unresolved global reference: CI, LI, and XXX, Assume that a search 
of the system library LB: [1,1] SYSLIB.OLB resolves LI and XXX, and TKB 
includes the defining modules in the task's image. Assume also that 
TKB cannot resolve the global symbol CI. TKB lists it as an undefined 
global symbol. 

The relocatable global symbol Bl is defined twice. TKB lists it as a 
multiply defined global symbol. TKB uses the first definition of that 
multiply defined symbol. 

Finally, an absolute global symbol (for example, symbol=100) can be 
defined more than once without being listed as multiply defined, as 
long as each occurrence of the symbol has the same value. 



2.2 THE TASK STRDCTDRE 

TKB builds the data structures required by other system programs and 
incorporates them into the task image. The Executive (which is 
responsible for the allocation of system resources) must have access 
to the data for all tasks on the system. It must know, for example, a 
task's size and priority, and it must have information about the way 
each task expects to use the system. It is the Task Builder's 
responsibility to allocate space in the task image for the data 
structures required by the Executive. For example, TKB allocates 
space for the task header and initializes it. 

The disk image file created by TKB contains the linked task and all of 
the information required by the system programs to install and run it. 
In its simplest form, the disk image file consists of three physically 
contiguous parts: 

• The label block group 

• The task header 

• The task memory image 

Figure 2-4 illustrates the basic simplified structure of this file. 

The label block group contains data produced by TKB and used by 
INSTALL command processing. It contains information about the task, 
such as the task's name, the partition in which it runs, its size and 
priority, and the logical units assigned to it. When you install the 
task, INSTALL command processing (hereinafter called INSTALL) uses 
this information to create a Task Control Block (TCB) entry for the 
task in the System Task Directory (STD) and to initialize the task's 
header information. 

The task's header contains information that the Executive uses when it 
runs the task. The header also provides a storage area for saving the 
task's essential data when the task is checkpointed . TKB creates and 
partially initializes the header; INSTALL initializes the rest of the 
header . 
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Figure 2-4 Disk Image of the Task 



The task memory contains the linked modules of the program and, 
therefore, the code and data. It also contains the task's stack. The 
stack is an area of task memory that a task can use for temporary 
storage and subroutine linkage. It can be referenced through general 
register 6, the stack pointer (SP) . The label block group, the task's 
header, and the task memory are described in detail in Appendix B. 

The task's memory image is the part of your task that the system reads 
into physical memory at run time. The label block group is not 
required in physical memory. Therefore, in its simplest form, the 
task's memory image consists of only two parts: the task header and 
task memory. Figure 2-5 shows the memory image. 



TASK 
: MEMORY : 



HEADER 



Figure 2-5 Memory Image 
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2 . 3 OVERLAYS 

This section is an introduction to overlaid tasks. Details about 
overlaid tasks can be found in Chapters 3 and 4. 

Using overlays can save memory space by reducing the size of the 
executing portion of the task or the physical memory required by the 
task. Parts of an overlaid task reside on disk, thereby saving memory 
space. 

An overlaid task is a task designed to have discrete parts. The parts 
of a task designed this way can execute relatively independently of 
other parts. Parts of an overlaid task reside on disk until they are 
needed for their required function. The common part of the task, 
which stays in memory, is the root. The root calls the other parts of 
the task, which are referred to as segments, from disk into memory. 

The RSX-llM/M-PLUS systems have two types of overlaid tasks. One type 
of overlaid task reads in segments from disk over other segments 
already in memory. A task of this type is called a disk-resident 
overlaid task. In this task, segments reside on disk until they are 
needed. The segments in disk-resident overlays that share the same 
memory address space of the task with other segments must be logically 
independent of those segments. The independence is necessary because 
the other segments are on disk and cannot be referenced. For example. 
Task A, an overlaid ta^k root, can call either of two 
segments: segment B or segment C. The root of Task A initially calls 
segment B. Segments B and C occupy the same memory space. Segment B 
cannot call segment C and segment C cannot call segment B. However, 
if segment B returns control of the task to the root of task A, the 
root can then call segment C. Segment C would then be read into 
memory over segment B. Figure 2-6 illustrates this sequence. 

Because segments of a disk-resident overlaid task can occupy the same 
memory space, a disk-overlaid task can occupy less memory than it 
would if it were not overlaid. However, more disk I/O transfers (and, 
therefore, more time) are needed for this type of task. 

Another type of overlaid task is the memory-resident overlaid task. 
In this task, the segments reside on disk until they are needed. At 
that time, the needed segment is read into a sequentially adjacent 
area of memory and resides there until the task ends. For example, a 
memory-resident overlaid Task A has two segments: segment B and 
segment C. If the root of task A calls segment B, segment B is read 
into memory adjacent to the root. When the root regains control and 
then calls segment C, segment C is read into memory adjacent to 
segment B. Figure 2-7 illustrates this sequence. 

Memory-resident overlaid tasks execute faster than disk-resident 
overlaid tasks. The increase in speed occurs because fewer disk I/O 
transfers are needed during task execution. 
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Figure 2-6 Simple 2-Segment, Disk-Resident Overlay Galling Sequence 
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2.4 ADDRESSING CONCEPTS 

The primary addressing mechanism of the PDP-11 is the 16-bit computer 
word. The maximum physical address space that the PDP-11 can 
reference at any one time is a function of the length of this word. 
Because of the 16-bit word size, a task can have an address no larger 
than 177777 (octal) (32K words) within the task image for nonprivileged 
tasks on an unmapped system. In practice, the task size may be 
limited to a few words less than 32K because of system design. 



2.4.1 Physical, Virtual, and Logical Addresses 

Physical, virtual, and logical addresses, and virtual and logical 
address space, are concepts that provide a basis for understanding the 
functions of task addressing and the use of task windows. 

• Physical addresses - A single, physical location in memory is 
called the physical address. 

Memory is divided into parts called bytes. They are numbered 
according to their position in memory. Therefore, the lowest 
byte is and the highest byte is whatever the upper limit of 
memory may be for a particular system; for example, 32K, 64K, 
and so forth. The assigned number is called the physical 
address. 

A task contains addresses (for example, through 2200). TKB 
relocates the task's addresses in an unmapped system by a 
number represented by the base address of the partition in 
which it is installed. After installation, the task's 
addresses refer to physical addresses of memory, which always 
correspond to the same physical memory in an unmapped system. 

Therefore, the task addresses have an actual one-to-one 
relationship to physical memory. The same relationship exists 
any time the task is in memory. The memory (physical) 
addresses will not be from through 2200. For example, after 
the task is installed in the partition, the task's address of 
may become physical address 17000 because the Task Builder 
added in the offset, which is equal to the partition base 
address . 

In a mapped system, the task's addresses remain the same but 
the physical memory addresses may change due to Executive 
processes (checkpointing, swapping, and so forth.). 
Therefore, the task addresses do not always correspond to the 
same physical memory. If the task uses memory management 
directives, the memory addressing can be changed by the task 
to include any part of physical memory that it is allowed to 
access. 

• Virtual addresses - A task's virtual addresses are the 
addresses within the task. 

The PDP-11 's 16-bit word length (a mapped system) imposes the 
address range of 32K words on the virtual addresses. 
Therefore, these task addresses could include addresses 
through 177777 (octal) depending on the length of the task. 
These task addresses are not the same as the actual addresses 
of the memory in which the task resides. 
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• Virtual address space - A task's virtual address space is that 
space encompassed by the range of virtual addresses that the 
task uses. 

With the Create Address Window (CRAW$) memory management 
directive, a task can divide its virtual address space into 
segments called virtual address windows. By using address 
windows, you can manipulate the mapping of virtual addresses 
to dififerent areas of physical memory. 

• Logical addresses - A task's logical addresses are the actual 
physical memory addresses that the task can access. 

• Logical address space - The task's logical address space is 
the total amount of physical memory to which the task has 
access rights. 

The physical memory represented by the logical addresses may 
or may not be continuous. The items in physical memory that 
logical address space includes are the task itself, and static 
and dynamic regions. 



2.4.2 Unmapped Systems 

In an unmapped system, the task's virtual address space and its 
logical address space coincide exactly, as shown in Figure 2-8. 

in an unmapped system, the task's address space is limited to 32K 
words. All of the machine's physical memory and all of its device 
registers are accessible to all tasks running on the system. The top 
4K words of address space are reserved for the UNIBUS addresses that 
correspond to the peripheral device registers (the I/O page) , and a 
segment of low memory is occupied by the Executive. Therefore, in an 
unmapped system, the largest task size is 32K words minus the I/O page 
and the size of the Executive. Figure 2-9 shows the memory layout for 
an unmapped system. 

Unmapped systems contain only user-controlled partitions. When TKB 
links the relocatable object modules of a task that is to run on an 
unmapped system, it requires that you specify the partition in which 
the task is to run, and the partition's base address and length. TKB 
sets the base address of the task to the base address of the 
partition. This means that the task's location in physical memory is 
bound to the partition and does not change. Because all of physical 
memory in an unmapped system is directly addressable, and the task's 
location within memory does not change, the addresses that TKB assigns 
coincide exactly with the physical addresses of the machine and, 
therefore, do not need to be relocated at run time. 



2.4.3 Mapped Systems 

A mapped system is one in which the processor contains a KT-11 memory 
management unit. The processor handbook for your machine contains a 
complete description of the memory management unit. 

Mapped processors have up to three modes of operation: kernel, 
supervisor, and user (the PDP-11/34 does not have supervisor mode). 
The information in this section is relevant to user mode only. 
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Figure 2-8 Virtual and Logical Address Space Coincidence 
in an unmapped System 



In a mapped system, the relationship between virtual address space and 
physical address space is different from that of an unmapped system. 
The primary addressing mechanism for a mapped system is still the 
16-bit word, and virtual address space is still 32K words. However, a 
mapped system has a much greater physical memory capacity and, 
therefore, physical memory and virtual address space do not coincide. 
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Figure 2-9 Memory Layout for Unmapped System 



The memory management unit divides a machine's 32K words of virtual 
address space into eight 4K-word segments or pages. Each page has two 
registers associated with it: 

• A 15-bit Page Description Register (PDR) , which contains 
control and access information about the page with which it is 
associated 



A 16-bit Page Address Register 
relocation register 



(PAR) , which is an address 



The PDRs and PARS are always used as a pair. Each pair is called an 
Active Page Register (APR) . Figure 2-11 shows how the memory 
management unit divides the 32K words of virtual address space. 

The Executive allocates only as many APRs as are necessary to map a 
given task into physical memory. Therefore, a 4K-word task requires 
one APR; a 6K-word task requires two. Figure 2-12 illustrates this 
mapping . 
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Figure 2-10 Task Relocation in a Mapped System 
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2.4.4 Regions 

This section briefly describes regions and their relationship to and 
use by tasks. Regions and their use are more thoroughly described in 
Chapter 5. 

A region is a defined area of memory that can contain code or data. 
It can also be a blank area reserved for use by one or more tasks. 
The region is named and built like a task except that the /HD header 
switch is negated (/-HD) because the region is not a task and does not 
need a task header. Tasks can also create regions dynamically as they 
execute. Dynamic regions are useful because they increase the task's 
logical address space while saving its virtual address space. Regions 
also allow tasks to share code and data with other tasks. 
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Figure 2-12 Mapping for 4K-Word and 6K-Word Tasks 

Regions are named according to their use or the way in which they were 
built. These regions are: 

_ „, —^ ■ » —-.^i.i^,,n,-,a Ki /-.r-v <-.f tnamnrv in which the task 

• TaSK Region — A >_Om.iiJu>-'"S »^j.«q.k. n-^ *>v^...^i.^ — .,_ij.^.. 

runs . 

• Common Shared Region — On unmapped systems, a shared region 
defined by an operator at run time or built into the system 
during system generation; for example, a global common area. 
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Resident commons are usually called shared regions because 
they are used as an area in which tasks share common data. 
Shared regions can be absolute or position independent. 
Shared regions and their use are described in Chapter 5. 

Library Shared Region — A shared region containing common 
code or routines shared by tasks, and in this way saving 
virtual address space in the tasks. 

Dynamic Region — A region created dynamically at run time by 
the Create Region (CRRG$) memory management directive in the 
task. This directive and associated directives are described 
m the RSX-llM/M-PLUS Executive Reference Manual . 

By convention, a shared region that contains code is a library and a 
shared region that contains data is a common. 

Tasks must map to a region by using task windows which must be defined 
and numbered in the task when the task is built. Usually, a task uses 
one window for each region to which mapping must occur. Task windows 
are described in the next section. Task Mapping and Windows. 

Figure 2-14 shows a sample collection of regions that could make up a 
task s logical address space. A task's logical address space can 
expand and contract dynamically as the task issues the appropriate 
memory management directives. The header and root segment are always 
part of the region. Therefore, the task header and root segment 
always use window (UAPR 0) and region 0. Because a region occupies 
^ continuous area of memory, each region is shown as a separate block 



a 



2.5 TASK MAPPING AND WINDOWS 



As mentioned earlier, tasks that run on mapped systems must be 
relocated at run time. When you build a task that is to run on a 
mapped system, TKB creates and places in the header of the task one or 
more 8-word data structures called window blocks, when you install a 
task, INSTALL initializes the window block(s) . Once initialized a 
window block describes a range of continuous virtual addresses called 
a window. 



2.5.1 Task Windows 



A window can be as small as 32 words or as large as 32K words. When a 
task consists of one continuous range of addresses (a single region 
task) only one window block is required to describe the entire task 
from the beginning of its header to the highest virtual address in thp 
tasK, when a task consists of two or more regions (such as a task 
that references a shared region as described in Chapter 5), each 
region must have at least one window block associated with it that 
describes all or a portion of the region. 

When the Executive maps a task into physical memory, it extracts the 
information it requires to set up the APRs of the memory management 
unit from the task's window block. 
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Figure 2-13 Window Block 



When you run your task, the Executive determines where in physical 
memory the task is to reside. The Executive then loads the Page 
Address Register portion of the APRs with a relocation constant that, 
when combined with the addresses of the task, yields the 18- or 22-bit 
physical address range of the task. 

Referring to Figure 2-14, which illustrates a mapped system without I- 
and D-space, you can observe that a large 32K user task contains three 
distinct areas of continuous space called "windows." The term "task 
window" is a construct that maps a continuous portion of the task's 
viri-uao. avjiaress space to a continuous portion of a region in the 
task's logical address space. Windows must have a specified size and 
starting address. The window size can be from 32 words to 32K minus 
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32 words, and windows must start on a 4K address boundary. Figure 
2-14 shows three windows that are not continuous in the task's virtual 
address space. However, the space within each window is continuous. 
In this task, the size of window is IIK; the size of window 1 is 
llK; and the size of window 2 is 8K. The concept of windows exists 
for the following specific reason. 

By using the concept of windows and the memory management directives, 
a nonprivileged task can access a larger logical memory space than 
that implied by the 32K virtual addressing range and normally 
accessible by the 16-bit address. A task can, in fact, only access 
32K of memory at one time. However, a nonprivileged task can change 
its access to logical addresses (real, physical memory). The area 
that your program accesses can be changed by the program during 
program execution- The process of accessing different logical areas 
of memory is called "mapping." 

By referring to Figure 2-14, you can see that window 1 in the task is 
mapped to region 1 in physical memory. The task can change the window 
1 mapping to region in physical memory. In effect, then, though a 
task is limited to a range of 32K virtual addresses, a task can access 
all the physical memory available to it (determined by the way that 
you set up the mapping) by changing the mapping of its windows to 
different logical addresses. Figure 2-14 provides a visual 
description of the concept of mapping to different logical addresses. 

The discussion now proceeds to setting up the task's windows. This is 
done by defining task window blocks to TKB. 

To manipulate virtual address mapping to various logical areas, you 
must first divide a task's 32K of virtual address space into segments. 
These segments are task (virtual address) windows. Each window 
encompasses a continuous range of virtual addresses. The first 
address of the window address range must be a multiple of 4K (the 
first address must begin on a 4K boundary) because of the way that the 
KT-11 memory management unit uses APRs . 

On an RSX-llM system, you can specify up to seven windows. Task 
mapping for the task's code requires the use of window 0. Therefore, 
there is a total of eight windows. However, window is not available 
to nonprivileged tasks. The size of each window can range from a 
minimum of 32 words to a maximum of 32K minus 32 words.' 

RSX-llM-PLUS tasks that use I- and D-space or supervisor-mode 
libraries have a total of 16 windows. You can specify up to 14 
windows in this type of task. Windows and 1 are not available to 
nonprivileged tasks in this kind of system. 

A task that includes directives that dynamically manipulate address 
windows must have task window blocks set up in the task header as well 
as Window Definition Blocks in the code for use by the Create Address 
Window directive. The Executive uses task window blocks to identify 
and describe each currently existing window. When linking the task, 
the programmer specifies the number of extra window blocks needed by 
the task. The number of blocks should equal the maximum number of 
windows that will exist concurrently while the task is running. 
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Figure 2-14 Virtual to Logical Address Space Translation 



TASK BDILDER FUNCTIONS 

In RSX-llM or RSX-llM-PLUS without I- and D-space, a window's 
identification is a number from to 7 , which is an index to the 
window's corresponding window block. The address window identified by 
is the window that always maps the task's header and root segment. 
TKB creates window 0, which the Executive uses to map the task. No 
directive may specify window 0; a directive that does so is rejected. 

In an RSX-llM-PLUS system using an I- and D-space task, n window's 
identification is a number from to 15, which is an index to the 
window's corresponding window block. The address windows identified 
by and 1 are the windows that always map the task's header and root. 
TKB creates windows and 1, which the Executive uses to map the task. 
No directive may specify windows or 1; a directive that does so is 
rejected. 

When a task uses memory management directives, the Executive views the 
relationship between the task's virtual and logical address space in 
terras of windows and regions. Unless a virtual address is part of an 
existing address window, the address does not point anywhere. This is 
a point to watch when setting up windows with the Create Address 
Window directive (CRAW$) . Similarly, a window can be mapped only to 
an area that is all or part of an existing region within the task's 
logical address space. 

Once a task has defined the necessary windows and regions, the task 
can issue memory management directives to perform operations such as 
the following: 

• Map a window to all or part of a region. 

• Unmap a window from one region in order to map it to another 
region. 

• Unmap a window from one part of a region in order to map it to 
another part of the same region. 



2.6 RSX-llM-PLUS SUPERVISOR MODE 

Three modes of operation are possible in the PDP-11: user mode, 
supervisor mode, and kernel mode. Each mode has associated with it 16 
APRS for mapping memory: 8 I-space APRs and 8 D-space APRs . A task 
in the RSX-llM-PLUS system can use supervisor-mode libraries and 
thereby double the task's virtual address, space to 64K words. 
Sapervisor-mode libraries are described in Chapter 8. This section 
briefly describes supervisor mode and the mapping that occurs when the 
task uses supervisor mode. 

Supervisor-mode libraries are libraries of routines that are used only 
in supervisor mode. .■ The task switches to supervisor mode when it 
calls a routine within the supervisor-mode library. By using a 
supervisor mode library as described in Chapter 8, you make the 
RSX-llM-PLUS system, for large systems, use the. supervisor-Mode APRs. 



• O • X 



Supervisor-Mode Mapping 



Normally, a task- has an address space of 32K-words by using eight user 
APRS.; When a conventional task links to a supervisor-mode library and 
calls a routine in the library, ■ the. Executive copies the user-mode 
I-space APRs into the supervisor-mode D-space [ APRs and maps the 
supervisor-mode library with supervisor l-space APRs. Therefore, 
while in. supervisor mode and within the .library, the task can access 
32K-words of its own space with D-space APRs and 32K-words of library 



2-24 



TASK BUILDER FDNCTIONS 

.;4(afe^";*''"-;;aE|ac€S;,^^ 'C|tcdef&M=,;;*|ttj]^;|''^tsq^ 

2.7 PRIVILEGED TASKS 

RSX-llM/M-PLUS systems have two classes of tasks: privileged and 
nonprivileged. However, the term "privileged" has meaning in mapped 
systems only, because in mapped systems certain areas of memory are 
protected from nonprivileged tasks. In an unmapped system, any task 
has the ability to access all of physical memory if so programmed. 
Therefore, the distinction between these two classes of tasks is 
primarily one of their mapping to memory in a mapped system. 

Privileged tasks in a mapped system can access system data areas and 
the Executive. Altering system data areas or the Executive can cause 
obscure and difficult problems. Therefore, privileged tasks must be 
progranimed and used with all caution. 

You can specify a task as privileged by using the /PR switch in the 
TKB command line. The /PR:0 switch allows a task to perform certain 
privileged operations; but, the /PR:0 task cannot access the 
Executive or system data structures. The /PR:4 switch allows the task 
to directly map the I/O page. Executive routines, and system data 
structures. The /PR:4 switch is used for a privileged task in a 
system that has an Executive of 16K or less. The /PR:5 switch allows 
a task to directly map to the I/O page. Executive routines, and system 
data structures. The /PR:5 switch is used for a privileged task in a 
system that has an Executive of 20K or less. 

Chapter 6 describes privileged tasks and their mapping in detail. 
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Using a Supervisor-Mode Library in an RSX-llM-PLOS System 
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2.8 HDI.TIDSER TASKS (RSX-llM-PLDS ONLY) 

The following section is an introduction to multiuser tasks, which are 
fully described in Chapter 9. 

TKB allows you to build multiuser tasks. A multiuser task is-, that 
which has one portion of its code and data designated as read-pnly arid 
another, portion designated as read/write. /You specify the, read-dnly 
portions of your task with program sections that have the read-only 
access code. V?hen you then build your task 'with the' /MU swi:tch> TKB 
places the read-only portions, iii a region that has a high virtual 
address and the read/write portion in. a region that has a low virtual' 
address. Any other requests to run the task, if the task is already 
ranning, results in a copy of the read /write portion ol the . ta,sk - in 
physical' memory; for the other user.. There. is always only Ane <;opy/of 
the . read-only code: regardless of the . namber . of tasks • 'that ■ may ■ be 
running.-.'.' —.'.■ •- ...;.'■■ '/' 

The /MU switch is described in Chapter 10. ,' 



2.9 USER-MODE I- AND D-SPACE TASKS (RSX-llM-PLUS) 

User tasks that use both I-' and D-space differ from conventional tasks 
because I- and D-space tasks have specifically defined locations 
within the task for both instructions and data. Because of this 
separation, the I- and D-space task image is structurally different. 

Additionally, the separate instruction areas are mapped through 
separate APRs in the memory management unit. Hence, up to 8 user-mode 
instruction APRs map the task's instructions, and up to 8 user-mode 
data APRs map the task's data. 

Also, overlaid I- and D-space tasks are more complex because each 
overlaid part (segment) of such a task may reside in both instruction 
space and data space. 

I- and D-space tasks differ from conventional tasks in the following 
major ways: 

• PSECTs with the "I" attribute contain only instructions and 
PSECTs with the "D" attribute contain only data. 

• Two sets of APRS map the I- and D-space task: the I-space 
APRS and the D-space APRs. 

• I- and D-space tasks can use up to 64K words of virtual space 
instead of 32K words because of their use of the two sets. of 
APRS, with supervisor-mode libraries, an I- and D-space task 






The following have data contiguously adjacent in memory, and 

instructions contiguously adjacent in memory: ■ . 

• Non-overlaid I- and D-space tasks .."'■.. ■ 

• Segments in an overlaid I- and D-space task that contain both 
I- and D-space 
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■ la: these tasks .or ^taslr :S e gm en tSjI-r space: PSECTs ' ; are, ; segregated : from 
^p-spape ' -PSECTs in memoryj': they cannot be intermixed. ,' , . 

;Ptg.urei- 2-17 show's a user-mode: I- and D-space task with data ' separated 
from - the instr-uGtions .arid mapped to memory tlirough two sets of 'fiPRs. 
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Figure 2-17: SimpliCied APR Mapping for an I- and D-space Task 

I- and D-space tasks are more fully described in Cnapter 7. The task 
images for both conventional and I- and D-space tasks are described in 
Appendix B. 
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CHAPTER 3 
OVERLAY CAPABILITY 



TKB provides you with the means to reduce the memory and/or virtual 
address space requirements of your task by using tree-like overlay 
structures created with the Overlay Description Language (ODL) . You 
can divide your conventional task into pieces called segments, which 
are loadable with one disk access. In an I- and D-sp^ice /-^t^k^J^i-aji' 
overlaid segment that contijins I- and D-space PSECTa'ifeiequi'reLp ;a 
maximum of two disk accesses to load the segment. The segments are 
the discrete parts of the overlay structure that form the tree. You 
can specify two kinds of overlay segments: those that reside on disk, 
and those that reside permanently in memory after being loaded from 
disk. 



3.1 OVERLAY STRDCTDRES 

To create an overlay structure, you divide a task into a series of 
segments consisting of: 

• A single root segment, which is always in memory 

• Any number of overlay segments, you must consider which either 
1) reside on disk and share virtual address space and physical 
memory with one another (disk-resident overlays) ; or 2) 
reside in memory and share only virtual address space with one 
another (memory-resident overlays)! 

Segments consist of one or more object modules, which in turn consist 
of one or more program sections. Segments that overlay each other 
must be logically independent; that is, the components of one segment 
cannot reference the components of another segment with which it 
shares virtual address space. In addition to the logical independence 
of the overlay segments, you must consider the general flow of control 
within the task when creating overlay segments. 

You must also consider the kind of overlay segment to create at a 
given position in the structure, and how to construct it. Dividing a 
task into disk-resident overlays saves physical space, but introduces 
the overhead activity of loading these segments each time they are 
needed — but are not present — in memory. Memory-resident 
overlays, on the other hand, are loaded from disk only the first time 
they are referenced. Thereafter, they remain in memory and are 
referenced by remapping. 



1. Note that memory-resident overlays can be used only if the hardware 
has a memory management unit, and if support for the memory management 
directives has been included in the system on which the task is to 
run. 
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Several large classes of tasks can be handled effectively when built 
as overlay structures. For example, a task that moves sequentially 
through a set of modules is well suited to use as an overlay 
structure. A task that selects one of a set of modules according to 
the value of an item of input data is also well suited to use as an 
overlay structure. 

Tasks that have separate I- and D-spaco may also use overlays where 
the roov. h.is inntructionr- and dat.'s separately defined by PSECTs, and 
e.Tch individual segment of the task olso ius inst i:u(;t i ons and data 
separately defined. Chapter 7 contains more informotion about I- and 
D-space tasks. 



3.1.1 Disk-Resident Overlay Structures 

Disk-resident overlays conserve virtual address space and physical 
memory by sharing them with other overlays. Segments that are 
logically independent need not be present in memory at the same time. 
They, therefore, can occupy a common physical area in memory (and, 
therefore, common virtual address space) whenever either needs to be 
used . 

The use of disk-resident overlays is shown in this section by an 

example, task TKl, which consists of four input files. Each input 

file consists of a single module with the same name as the file. The 
task is built by the command 

>TKB TK1=0VRLAY.0DL/MP 

and the file OVRLAY.ODL contains the modules CNTRL, A, B, C in an 
overlay description for the task being built. The /MP switch 
specifies that the input file is an Overlay Description Language (ODL) 
file. 

In this example, the modules A, B, and C are logically independent; 
that is: 

A does not call B or C and does not use the data of B or C. 

B does not call A or C and does not use the data of A or C. 

C does not call A or B and does not use the data of A or B. 

A disk-resident overlay structure can be defined in which A, B, and C 
are overlay segments that occupy the same storage area in physical 
memory. The flow of control for the task is as follows: 

CNTRL calls A and A returns to CNTRL. 

CNTRL calls B and B returns to CNTRL. 

CNTRL calls C and C returns to CNTRL. 

CNTRL calls A and A returns to CNTRL. 

In this example, the loading of overlays occurs only four times during 

the execution of the task. Therefore, the virtual address space and 

physical memory requirements of the task can be reduced without unduly 
increasing the overhead activity. 

The effect of the use of an overlay structure on allocating virtual 
address space and physical memory for task TKl is described in the 
following paragraphs. 
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The lengths of the modules are: 

Module Length (in Octal) 

CNTRL 20000 bytes 

A 30000 bytes 

B 20000 bytes 

C 14000 bytes 

Figure 3-1 shows the virtual address space and physical memory 
required as a result of building TKl as a single-segment task on a 
system with memory management hardware. 

The virtual address space and physical memory requirement to build TKl 
as a single-segment task is 104000 (octal) bytes. 

In contrast. Figure 3-2 shows the virtual address space and physical 
memory required as a result of building TKl as a multisegment task and 
using the overlay capability. 

The multisegment task requires 50000 (octal) bytes. 

NOTE 

In addition to the storage required for 
modules A, B, and C, storage is required 
for overhead in handling the overlay 
structures. This overhead is not 
reflected in this example. 

In using the overlay capability, the total amount of virtual address 
space and physical memory required for the task is determined by the 
sum of the length of the root segment and the length of the longest 
overlay segment. Overlay segments A and B in this example are much 
longer than overlay segment C. If A and B are divided into sets of 
logically independent modules, task storage requirements can be 
further reduced. Segment A can be divided into a control program (AO) 
and two overlays (Al and A2) . Segment A2 can then be divided into the 
main part (A2) and two overlays (A21 and A22) . Similarly, segment B 
can be divided into a control module (BO) and two overlays (Bl and 
B2) . 

Figure 3-3 shows the virtual address space and physical memory 
required for the task produced by the additional overlays defined for 
A and B. 

As a single-segment task, TKl requires 104000 (octal) bytes of virtual 
address space and physical memory. The first overlay structure 
reduces the requirement by 34000 (octal) bytes. The second overlay 
structure further reduces the requirement by 14000 (octal) bytes. 

The vertical and horizontal lines in the diagrams of Figures 3-2 and 
3-3 represent the state of virtual address space and physical memory 
at various times during the calling sequence of TKl. For example, in 
Figure 3-3 the leftmost vertical line in both diagrams shows virtual 
address space and physical memory, respectively, when CNTRL, AO, and 
Al are loaded. The next vertical line shows virtual address space and 
physical memory when CNTRL, AO, A2, and A21 are loaded, and so on. 
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The horizontal lines in the diagrams of Figures 3-2 and 3-3 indicate 
segments that share virtual address space and physical memory. For 
example, in Figure 3-3, the uppermost horizontal line of the task 
region in both diagrams shows Al, A21, A22, Bl, B2 , and C, all of 
which can use the same virtual address space and physical memory. The 
next horizontal line shows Al, A2 , Bl, B2, and C, and so on. 
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Figure 3-2 TKl Built As a Multisegment Task 



3.1.2 Memory- Resident Overlay Structures <Not Supported on RSX-llS) 

TKB provides for creating overlay segments that are loaded from disk 
only the first time they are referenced. Thereafter, they reside in 
memory. Memory-resident overlays share virtual address space just as 
disk-resident overlays do but, unlike disk-resident overlays, 
memory-resident overlays do not share physical memory. Instead, they 
reside in separate areas of physical memory, each segment aligned on a 
32-word boundary. Memory-resident overlays save time for a running 
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task because they do not need to be copied from a secondary storage 
device each time they are to overlay other segments. "Loading" a 
memory-resident overlay reduces to mapping a set of shared virtual 
addresses to the unique physical area of memory containing the 
overlaying segment. 

The use of memory-resident overlays is shown in this section by an 
example, task TK2, which consists of four input files. Each input 
file consists of a single module with the same name as the file. The 
task is built by the command 

>TKB TK2=OVRLAY2.0DL/MP 

and the file 0VRLAY2.0DL contains the modules CNTRL, D, E, and F in an 
overlay description for the task being built. The /MP switch 
specifies that the input file is an Overlay Description Language (ODL) 
file. 

In this example, the modules D, E, and F are logically independent; 
that is: 

D does not call E or F and does not use the data of E or F. 

E does not call D or F and does not use the data of D or F. 

F does not call D or E and does not use the data of D or E. 

A memory-resident overlay structure can be defined in which D, E, and 

F are overlay segments that occupy separate physical memory locations 

but the same virtual address space. The flow of control for the task 
is as follows: 

CNTRL calls D and D returns to CNTRL. 

CNTRL calls E and E returns to CNTRL. 

CNTRL calls F and F returns to CNTRL. 

The effect of the use of a memory-resident overlay structure on 
allocating virtual address space and physical memory for task TK2 is 
described in the following paragraphs. 

The lengths of the modules are: 

Module Length (in Octal) 

CNTRL 20000 

D ibooo 

E 14000 

F 12000 

Figure 3-4 shows the virtual address space and physical memory 
requirements as a result of building TK2 as a single-segment task on a 
system with memory management hardware. 

The virtual address space and physical memory requirements when TK2 is 
built as a single-segment task is 56000 (octal) bytes. 

If TK2 is built using the Task Builder's memory-resident overlay 
capability, the relationship of virtual address space to physical 
memory changes, as shown in Figure 3-5. 
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Figure 3-5 TK2 Built As a Memory-Resident Overlay 

The physical memory requirements for TK2 do not change (56000 (octal) 
bytes) , but the virtual address space requirements have been reduced 
y.^ jiuuu v'-'w i-aj. ; u j i.ea . iu±o i. cpr eseiit s a savings m virt:ua± aaaress 
space of 22000 (octal) bytes. 
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NOTE 



In addition to the storage required for 
modules D, E, and F, storage is required 
for overhead in handling the overlay 
structures. This overhead is not 
reflected in this example. 

In Figure 3-5, the vertical and horizontal lines in the virtual 
address space diagram represent the state of virtual address space at 
various times during the calling sequence of TK2 . The leftmost 
vertical line shows virtual address space when CNTRL and D are loaded 
and mapped. The next vertical line shows virtual address space when 
CNTRL and E are loaded and mapped. The third vertical line shows 
virtual address space when CNTRL and F are loaded and mapped. 

The uppermost horizontal line of the task region shows that segments 
D, E, and F share virtual address space. 

When TK2 is activated, the Executive loads TK2 ' s root segment into 
physical memory. The Executive loads segments D, E, and F into memory 
as they are called. Once all segments in the structure have been 
called, "loading" of the overlay segments reduces to the remapping of 
virtual address space to the physical locations in memory where the 
overlay segments permanently reside. Figures 3-6 and 3-7 illustrate 
the relationship between virtual address space and physical memory for 
task TK2 during four time periods: 

• TIME 1 (Figure 3-6A) - TK2 is run and the system loads the 
root segment (CNTRL) into physical memory and maps to it. 

• TIME 2 (Figure 3-6B) - CNTRL calls segment D. The system 
loads segment D into physical memory and maps to it. Segment 
D returns to CNTRL. 

• TIME 3 (Figure 3-7A) - CNTRL calls segment E. The system 
loads segment E into physical memory, unmaps from segment D, 
and maps to segment E. Segment E returns to CNTRL. 

• TIME 4 (Figure 3-7B) - CNTRL calls segment F. The system 
loads segment F into physical memory, unmaps from segment E, 
and remaps to segment F. Segment F returns to CNTRL. 
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Figure 3-6A Time 1 
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Figure 3-6A Relationship Between Virtual Address Space 
and Physical Memory — Time 1 
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Figure 3-6B Time 2 
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Figure 3-6B Relationship Between Virtual Address Space 
and Physical Memory -- Time 2 
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Figure 3-7A Time 3 
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Figure 3-7A Relationship Between Virtual Address Space 
and physical Memory -- Time 3 
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Figure 3-7B Time 4 
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Figure 3-7B Relationship Between Virtual Address Space 
and physical Memory — Time 4 



It is important to be careful in choosing whether to have 
memory-resident overlays in a structure. Carelessly using these 
segments can result in inefficient allocation of virtual address 
space, because TKB allocates virtual address space in blocks of 4K 
words. Consequently, the length of each overlay segment should 
approach that limit if you are to minimize waste. (A segment that is 
one word longer than 4K words, for example, is allocated 8K words of 
virtual address space. All but one word of the second 4K words is 
unusable . ) 
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You can also conserve physical memory by maintaining control over the 
contents of each segment. Including a module in several 
memory-resident segments that overlay one another causes physical 
memory to be reserved for each extra copy of that module. Common 
modules, including those from the system object module library 
(SYSLIB) , should be placed in a segment that can be accessed from all 
referencing segments. 

The primary criterion for choosing to have memory-resident overlays is 
the need to save virtual address space when disk-resident overlays are 
either undesirable (because they would slow down the system 
unacceptably) , or impossible (because the segments are part of a 
resident library or other shared region that must permanently reside 
in memory) . 

Memory-resident overlays can help you use large systems to better 
advantage because of the time savings realized when a large amount of 
physical memory is available. Resident libraries, in particular, can 
benefit from the virtual address space saved when they are divided 
into memory-resident segments. 



3.2 OVERLAY TREE 

The arrangement of overlay segments within the virtual address space 
of a task can be represented schematically as a tree-like structure. 
Each branch of the tree represents a segment. Parallel branches 
denote segments that overlay one another and therefore have the same 
virtual address; these segments must be logically independent. 
Branches connected end to end represent segments that do not share 
virtual address space with each other; these segments need not be 
logically independent. 

TKB provides an Overlay Description Language (ODL) for representing an 
overlay structure consisting of one or more trees (the ODL is 
described in Section 3.4). 

The single overlay tree shown in Figure 3-8 represents the allocation 
of virtual address space for TKl (see Section 3.1.1). 

The tree has a root (CNTRL) and three main branches (AO, BO, and C) . 
It also has six leaves (Al, A21, A22, Bl, B2 , and C) . 

The tree has as many paths as it has leaves. The path down is defined 
from the leaf to the root. For example: 

A21-A2-A0-CNTRL 

The path up is defined from the root to the leaf. For example: 

CNTRL-BO-Bl 

Knowing the properties of the tree and its paths is important to 
understanding the overlay loading mechanism and the resolution of 
global symbols. 
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Figure 3-8 Overlay Tree for TKl 



3.2.1 Loading Mechanism 

Modules can call other modules that exist on the same path. The 
module CNTRL (Figure 3-8) is common to every path of the tree and, 
therefore, can call and be called by every module in the tree. The 
module A2 can call the modules A21, A22, AO, and CNTRL; but A2 cannot 
call Al, Bl, B2, BO, or C. 

When a module in one overlay segment calls a module in another overlay 
segment, the called segment must be in memory and mapped, or must be 
brought into memory. The methods for loading overlays are described 
in Chapter 4. 



3.2.2 Resolution of Global Symbols in a Multisegment Task 

In resolving global symbols for a multisegment task, TKB performs the 
same activities that it does for a single-segment task. The rules 
defined in Chapter 2 for resolving global symbols in a single-segment 
task apply also in this case, but the scope of the global symbols is 
altered by the overlay structure. 

In a single-segment task, any module can refer to any global 
definition. In a multisegment task, however, a module can only refer 
to a global symbol that is defined on a path that passes through the 
called segment. 

The following points, illustrated in the tree diagram in Figure 3-9, 
describe the two distinct cases of multiply defined symbols and 
ambiguously defined symbols. 

In a single-segment task, if you define two global symbols with the 
same name, the symbols are multiply defined and an error message is 
produced . 

In a multisegment task, you can define two global symbols with the 
same name if they are on separate paths, and not referenced from a 
segment that is common to both. 

If you define a global symbol more than once on separate paths, but 
they are referenced from a segment that is common to both, the symbol 
is ambiguously defined. If you define a global symbol more than once 
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TKB's procedure for resolving global symbols is summarized as follows: 

1. TKB selects an overlay segment for processing. 

2. TKB scans each module in the segment for global definitions 
and references. 

3. If the symbol is a definition, TKB searches all segments on 
paths that pass through the segment being processed, and 
looks for references that must be resolved. 

4. If the symbol is a reference, TKB performs the tree search as 
described in step 3, looking for an existing definition. 

5. If the symbol is new, TKB enters it in a list of global 
symbols associated with the segment. 

Overlay segments are selected for processing in an order corresponding 
to their distance from the root. That is, TKB processes the segment 
farthest from the root first, before processing an adjoining segment. 

When TKB processes a segment, its search for global symbols proceeds 
as follows: 

1. The segment being processed 

2. All segments toward the root 

3. All segments away from the root 

4. All co-trees (see Section 3.5) 

Figure 3-9 illustrates the resolution of global symbols in a 
multisegment task. 
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Fiaure 3-9 Resolution of Global Svmbols in a Multiseament Task 
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The following notes discuss the resolution of references in Figure 
3-9: 

1. The global symbol Q is defined in both segment AO and segment 
BO. The references to Q in segment A22 and in segment Al are 
resolved by the definition in AO . The reference to Q in Bl 
is resolved by the definition in BO. The two definitions of 
Q are distinct in all respects and occupy different overlay 
paths . 

2. The global symbol R is defined in segment A2 . The reference 
to R in A22 is resolved by the definition in A2 because there 
is a path to the reference from the definition 
(CNTRL-A0-A2-A22) . The reference to R in Al, however, is 
undefined because there is no definition for R on a path 
through Al. 

3. The global symbol S is defined in both segment AO and segment 
BO. References to S from segments Al, A21, or A22 are 
resolved by the definition in AO, and references to S in Bl 
and B2 are resolved by the definition in BO. However, the 
reference to S in CNTRL cannot be resolved because there are 
two definitions of S on separate paths through CNTRL. The 
global symbol S is ambiguously defined. 

4. The global symbol T is defined in both segment A21 and 
segment AO . Since there is a single path through the two 
definitions (CNTRL-A0-A2-A21) , the global symbol T is 
multiply defined. 



3.2.3 Resolution of Global Symbols from the Default Library 

The process of resolving global symbols may require two passes over 
the tree structure. The global symbols discussed in the previous 
section are included in user-specified input modules that TKB scans in 
the first pass. If any undefined symbols remain, TKB initiates a 
second pass over the structure in an attempt to resolve such symbols 
by searching the default object module library (normally 
LBO: [1,1] SYSLIB.OLB) . TKB reports any undefined symbols remaining 
after its second pass. 

When multiple tree structures (co-trees) are defined, as described in 
Section 3.5, any resolution of global symbols across tree structures 
during a second pass can result in multiple or ambiguous definitions. 
In addition, such references can cause overlay segments to be 
inadvertently displaced from memory by the overlay loading routines, 
thereby causing run-time failures. To eliminate these conditions, the 
tree search on the second pass is restricted to: 

• The segment in which the undefined reference has occurred 

• All segments in the current tree that are on a path through 
the segment 

• The root segment 

When the current segment is the main root, the tree search is extended 
to all segments. You can unconditionally extend the tree search to 
all segments by including the /FU (full) switch in the task image file 
specification. (Refer to Chapter 10 for a description of the /FU 
switch .) 
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3.2.4 Allocation of Program Sections in a Multisegment Task 

One of a program section's attributes indicates whether the program 
section is local (LCL) to the segment in which it is defined or is 
global (GBL) . 

Local program sections with the same name can appear in any number of 
segments. TKB allocates virtual address space for each local program 
section in the segment in which it is declared. Global program 
sections that have the same name, however, must be resolved by TKB. 

When a global program section is defined in several overlay segments 
along a common path, TKB allocates all virtual address space for the 
program, section in the overlay segment closest to the root. 

FORTRAN common blocks are translated into global program sections with 
the overlay (OVR) attribute. In Figure 3-10, the common block COMA is 
defined in modules A2 and A21. TKB allocates the virtual address 
space for COMA in A2 because that segment is closer to the root than 
the segment that contains A21. 

If the segments AO and BO use the common block COMAE, however, TKB 
allocates the virtual address space for COMAB in both the segment that 
contains AO and the segment that contains BO. AO and BO cannot 
communicate through COMAB. When the overlay segment containing BO is 
loaded, any data stored in COMAB by AO is lost. 

You can specify the allocation of program sections explicitly. If AO 
and BO need to share the contents of COMAB, you can force the 
allocation of this program section into the root segment by the use of 
the .PSECT directive of the Task Builder's overlay description 
language, described in Section 3.4. 
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Figure 3-10 Resolution of Program Sections for TKl 



3.3 OVERLAY DATA STRUCTORES AND RUN-TIME ROUTINES 



When TKB constructs an overlaid task it 
structures and adds them to 
contain information about the 
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the task image. The data structures 
overlay segments and describe the 
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relationship of each segment in the tree to the other segments in the 
tree. TKB also includes into the task image a number of system 
library routines (called overlay run-time routines) . The overlay 
run-time routines use the data structures to facilitate the loading of 
the segments and to provide the necessary linkages from one segment to 
another at run time. 

TKB links the majority of data structures and all of the overlay 
run-time routines into the root segment of the task. The number and 
type of data structures, and the functions the routines perform, 
depend on two considerations: 

• Whether the task is built to use the Task Builder's autoload 
or manual load facilities 

• Whether the overlay segment is memory resident or disk 
resident 

These considerations have a marked impact on the size and operation of 
the task. Chapter 4 describes the Task Builder's autoload and manual 
load facilities and describes the methods for loading overlays. 
Appendix B describes the data structures and their contents in detail. 

The contents of the root segment for a task with an overlay structure 
are discussed briefly in the following sections. 



3.3.1 Overlaid Conventional Task Structures 

Depending on the considerations just discussed, some or all of the 
following data structures are required by the overlay run-time 
routines : 

• Segment tables 

• Autoload vectors 

• Window descriptors 

• Region descriptors 

Figure 3-11 shows a typical overlay root segment structure. 

There is a segment descriptor for every segment in the task. The 
descriptor contains information about the load address, the length of 
the segment, and the tree linkage. 

In an autoloadable , overlaid task, autoload vectors appear in the root 
segment and in every segment that calls modules in another segment 
located farther away from the root of the tree. All references to 
resident libraries are resolved through autoload vectors in the root. 

Window descriptors are allocated whenever a memory-resident overlay 
structure is defined for the task. The descriptor contains 
information required by the Create Address Window system directive 
{CRAW$) . One descriptor is allocated for each memory-resident overlay 
segment . 

Region descriptors are allocated whenever a task is linked to a shared 
region containing memory-resident overlays. The descriptor contains 
information required by the Attach Region system directive (ATRG$) . 
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Figure 3-11 Typical Overlay Root Segment Structure 

3.3.2 Overlaid I- and D-Space Task Structures 

Overlaid I- and D-space tasks contain data structures similar to those 
in a conventional task. These data structures dirCer only in their 
virtual address space allocation (mapping) , and some structures are 
mapped in two different address spaces. 

Figure 3-12 shows a typical overlaid I- and D-space task with an 
up- tree segment. 

The structures located in data space are: 

• Segment descriptors 
r • , ..Wihdow' descriptors 

• Region descriptors 

■ ■•' Autoload vectors (the data part) 

Autoload vectors ooutaih data and instructions. Therefore, TKB 
locates the instruction part of the autoload vector in I-space and the 
data part in D-space.: Each segment of an autoloadable overlaid I- and 
D-space task may have an instruction part and a data part. Therefore ,- 
each J- and D-space segment in such a task would have its vectors 
separated into an instruction part and a data part. 
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The Structures located in instruction space are: 

• Autoload vectors (instruction part) 

• Segment return point 

• Overlay runtime system code (root segment only) 
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Figure 3-12 Typical Overlaid I- and ;D-Space Task with Up-Tree Segment 
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3.4 OVERLAY DESCRIPTION LANGUAGE 

TKB provides a language, called the Overlay Description Language 
(ODL) , that allows you to describe the overlay structure of a task. 
An overlay description is a text file consisting of a series of ODL 
directives, one directive per line. Each line may have as many as 132 
characters. You enter the name of this file in a TKB command line, 
and identify it as an ODL file by specifying the /MP switch (see 
Chapter 10) to the file name. For example, the following TKB command 
line specifies an ODL file: 



>TKB TASK1=0VRLAY/MP 

If you specify an ODL file to TKB, it must be the only input file you 
specify. 

A command line in an ODL file takes the form 

label: directive argument-list ;comment 

A label is required only for the .FCTR directive (see Section 3.4.2). 
Labels cannot be used with the other directives. 

The ODL directives are listed below and described in Sections 3.4.1 
through 3.4.6: 

.ROOT and .END 

.FCTR 

.NAME 

.PSECT 

@ (at sign; indirect command file specifier) 

The ODL directives can act upon the following items: named input 
files, overlay segments, program sections, and lines in the ODL file 
itself. These items follow each directive on the same line as the 
directive, and form an argument-list. Operators, such as the hyphen, 
exclamation point, and comma, group the argument-list items (named 
task elements) or attach attributes to them. 

If the named task element is a file, you can enter a complete file 
specification. Defaults for omitted parts of the file specification 
are as described in Chapters 1 and 10, except that the default device 
is SYO:, and the default UFD is taken from the terminal UIC. 

In addition, the following restrictions apply to argument-lists: 

• You can only use the dot character (.) in a file name. 

• Comments cannot appear on a line ending with a file name. 



3.4.1 .ROOT and .END Directives 

The .ROOT directive defines the structure of the overlaid task. 
Because of this, .ROOT usually appears first in the overlay 
description. The .NAME directive may precede the .ROOT directive in 
certain circumstances discussed in Section 3.4.4. Each overlay 
description must end with one .END directive. The .ROOT directive 
tells TKB where to start building the tree, and the .END directive 
tells TKB where the input ends. 
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The arguments of the .ROOT directive use three operators to express 
concatenation, memory residency, and overlaying. These operators can 
be used also in the .FCTR directive. 

• The hyphen (-) operator indicates the concatenation of virtual 
address space. For example, X-Y means that sufficient virtual 
address space will be allocated to contain module X and module 
Y simultaneously. TKB allocates segment X and segment Y in 
sequence to produce one segment . 

• The exclamation point (!) operator indicates memory residency 
of overlays. (This operator is discussed in Section 3.4.3.) 

• The comma (,) operator, appearing within parentheses, 
indicates the overlaying of virtual address space. For 
example, (Y,Z) means that virtual address space can contain 
either segment Y or segment Z. If no exclamation point (!) 
precedes the left parenthesis, segment Y and segment Z also 
share physical memory. 

The comma (,) operator is also used to define multiple tree 
structures (as described in Section 3.5.1). 

You use parentheses to delimit a group of segments that start at the 
same virtual address. The number of nested parenthetical groups 
cannot exceed 16. 

For example: 

.ROOT X-(Y,Z-(Z1,Z2) ) 
.END 

These directives describe the tree and its corresponding virtual 
address space shown in Figure 3-13: 



Z1 Z2 



Y 


Z1 




Z2 


z 


X 



X 

ZK-406-81 

Figure 3-13 Tree and Virtual Address Space Diagram 

To create the overlay description for the task TKl in Figure 3-3 
(Section 3.1.1), you could create a file called TFIL.ODL that contains 
the directives: 

.ROOT CNTRL-(A0-(A1,A2-(A21,A22)) ,B0-(B1,B2) ,C) 
.END 

To build the task with that overlay structure, you would type: 

>TKB TK1=TFIL/MP 

The /MP switch in the command string above tells TKB that there is 
only one input file (TFIL.ODL) , and that this file contains the 
overlay description for the task. 
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3.4,2 .FCTR Directive 

The .FCTR directive allows you to build large, complex trees and 
represent them clearly. 

The .FCTR directive has a label at the beginning of the ODL line that 
is pointed to by a reference in a .ROOT or another .FCTR statement. 
The label must be unique with respect to module names and other 
labels. The .FCTR directive allows you to extend the tree description 
beyond a single line, enabling you to provide a clearer description of 
the overlay. (There can be only one .ROOT directive.) 

For example, to simplify the tree given in the file TFIL (described in 
Section 3.4.1), you could use the .FCTR directive in the overlay 
description as follows: 

.ROOT CNTRL-(AFCTR,BFCTR,C) 
AFCTR: .FCTR A0-(A1,A2-(A21,A22) ) 
BFCTR: .FCTR B0-(B1,B2) 

.END 

The label BFCTR is used in the .ROOT directive to designate the 
argument B0-(B1,B2) of the .FCTR directive. The resulting overlay 
description is easier to interpret than the original description. The 
tree consists of a root, CNTRL, and three main branches. Two of the 
main branches have sub-branches. 

The .FCTR directive can be nested to a level of 16. For example, you 
could further modify TFIL as follows: 

.ROOT CNTRL- (AFCTR, BFCTR, C) 

AFCTR: .FCTR AO- ( Al , A2FCTR) 

A2FCTR: .FCTR A2-(A21,A22) 

BFCTR: .FCTR B0-(B1,B2) 

.END 



3.4.3 Arguments for the .FCTR and .ROOT Directives 

The arguments for the .FCTR and .ROOT directives may have different 
forms or syntax. The examples in this chapter use forms such as Al, 
Bl, X, and Y for clarity, but the actual arguments that you use may 
have somewhat different names. This section lists the forms that the 
arguments may take for these directives. If you use an argument that 
does not fall into one of the following five categories, TKB takes the 
argument as that of the name of an object module file; in other 
words, the file name that you use must have an extension of .OBJ. 



3.4.3.1 Named Input File - You may use a named input file that has 
the object file format. For example, 

CALC: .FCTR [7, 54] MULT. OB J 

The default is .OBJ. 
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3.4.3.2 Specific Library Modules - you may name and therefore 
specific object modules from a library file. For example. 



use 



BAKER: 



.FCTR [300,3]COOKIE/LB:CHIP:OAT 



where COOKIE. OLE is the library file and CHIP and OAT are the modules 
that you want to extract from the file. The default extension is .OLE 
and it need not be specified as part of the argument. 



3.4.3.3 A Library to Resolve References Not Previously Resolved - You 

may specify a library as an argument in a .FCTR statement after 
extracting specific modules in a previous .FCTR statement. TKB uses 
the library to resolve symbols that may still be unresolved after 
extracting the modules. For example. 



BAKER: .FCTR [300 , 3] C0OKIE/LB:CHIP:OAT 
LIB: .FCTR LB: [1,4] RECIPE/LB 



3.4.3.4 A Section Name Osed in a .PSECT Directive - You may use the 
name that you used as a program section name in the .PSECT directive 
as the argument in a .FCTR statement. For example. 



.PSECT 
FSTCOM: .FCTR 



COM,GBL,D,RW,OVR 
COM 



3.4.3.5 A Segment Name Used in a .NAME Directive - You may use the 

name that you specified as the name of a segment in the .NAME 



directive. For example. 



.NAME SEG1,GBL,DSK 
OVLY: .FCTR SEG1-M0D1-M0D2 



3.4.4 Exclamation Point Operator 

The exclamation point operator allows you to specify memory-resident 
overlay segments (see Section 3.1.2). You specify memory residency by 
placing an exclamation point (!) immediately before the left 
parenthesis enclosing the segments to be affected. The overlay 
description for task TK2 in Figure 3-4 (Section 3.1.2) is as follows: 

.ROOT CNTRL-! (D,E,F) 
.END 

In the example above, segments D, E, F are declared resident in 

separate areas of physical memory. The Task Builder determines the 

single starting virtual address for D, E, and F by rounding the octal 

length of segment CNTRL up to the next 4K boundary. The physical 

memory allocated to segments D, E, and F is determined by rounding the 

actual length of each segment to the next 32-word boundary (255-word 
boundary if the /CM switch is in effect) , and adding this value to the 
total memory required by the task. 



3-26 



OVERLAY CAPABILITY 



The exclamation point operator applies to that segment immediately to 
the right of the left parenthesis and those segments farther from the 
root on the same level with that segment. In other words, all 
parallel segments must be of the same residency type (disk resident or 
memory resident) . 

The exclamation point operator applies to segments at the same level 
from the root inside a pair of parentheses; segments nested in 
parenthesis within that level, but farther from the root, are not 
affected. 

It is therefore possible to define an overlay structure that combines 
the space-saving attributes of disk-resident overlays with the speed 
of mem.ory-resident overlays. For exam.ple: 

.ROOT A-! (B1-(B2,B3) ,C) 
.END 

In this example, Bl and C are declared memory resident by the 
exclamation point operator. B2 and B3 are declared disk resident, 
however, because no exclamation point operator precedes the 
parentheses enclosing them. 

Note that while a memory-resident overlay can call a disk-resident 
overlay, the converse is not legal; that is, you cannot use an 
exclamation point for segments emanating from a disk-resident segment. 
For example, you cannot build the following structure: 



.ROOT A-(B1-! (B2,B3) ,C) 
.END 



this overlay description is illegal 



In this example, Bl is declared disk resident; so it is illegal 
use the exclamation point to declare B2 and B3 memory resident. 



to 



3.4.5 



.NAME Directive 



The .NAME directive allows you to name a segment 
attributes to the segment. The name must be unique w 
file names, program section names, .FCTR labels, and 
names used in the overlay description. You use the 
prior to using the .ROOT or .FCTR directive. The 
attaches attributes to a segment when it encounters 
.ROOT or .FCTR directive that defines the overlay segm 
apply multiple names to a segment, the attributes of 
given are in effect. This directive does the following: 



, and assign 

ith respect to 

other segment 

NAME directive 

Task Builder 

the name in a 

ent . If you 

the last name 



• Names uniquely a segment that is loaded through the manual 
load facility (see Chapter 4) 

• Permits a named data-only segment to be loaded through the 
autoload mechanism 

The format of the .NAME directive is: 



.NAME segname [ ,attr] [ ,attr] 



segname 



A 1- to 6-character name; this name can consist of the Radix-50 
characters A-Z, 0-9, and $ (the period (.) cannot be used). 
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attr 



One of the following 
GBL 



NODSK 



NOGBL 



DSK 



The name is entered in the segment's global symbol 
table. 

The GBL attribute makes it possible to load 
data-only overlay segments by means of the autoload 
mechanism (see Chapter 4) . 

No disk space is allocated to the named segment. 

If a data overlay segment has no initial values, but 
will have its contents established by the running 
task, no space for the named segment on disk need be 
reserved. If the code attempts to establish initial 
values for data in a segment for which no disk space 
is allocated (a segment with the NODSK attribute) , 
TKB gives a fatal error. 

The name is not entered in the segment's global 
symbol table. 

If the GBL attribute is not present, NOGBL is 
assumed . 

Disk storage is allocated to the named segment. 

If the NODSK attribute is not present, DSK is 
assumed . 



3.4.5.1 Example of The Ose of The .NAME Direct 
modified ODL file for TKl (Figure 3-3 of Sect 
names for the three main branches, AO , BO, and 
names in the .NAME directive and using them 
The default attributes NOGBL and DSK are in e 
BRNCH3, but BRNCH2 has the complementary att 
that cause TKB to enter the name BRNCH2 into 
symbol table and suppress disk allocation fo 
contains uninitialized storage to be utilized a 



ive - In the following 
ion 3.1.1), you provide 
C, by specifying the 
in the .ROOT directive, 
ffect for BRNCHl and 
ributes (GBL and NODSK) 
the segment's global 
r that segment. BRNCH2 
t run time. 



AFCTR: 
BFCTR: 



.NAME BRNCHl 

.NAME BRNCH2, GBL, NODSK 

.NAME BRNCH3 

.ROOT CNTRL-! (BRNCH1-AFCTR,*BRNCH2-BFCTR,BRNCH3-C) 

.FCTR A0-{A1,A2-(A21,A22) ) 

.FCTR BO-*! (B1,B2) 

. END 



(The asterisk (*) is the autoload indicator; it is discussed in 
Chapter 4.) 

You can load the data overlay segment BRNCH2 by including the 
following statement in the program: 

CALL BRNCH2 

This action is immediately followed by an automatic return to the next 
instruction in the program. 
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YOU can also use segment names in making patches with the ABSPAT and 
GBLPAT options {see Chapter 11) . 

NOTE 

In the absence of a unique .NAME 
specification, TKB establishes a segment 
name, using the first module name or 
library module name occurring in the 
segment. 



3.4.6 .PSECT Directive 

You can use the .PSECT directive to control the placement of a global 
program section in an overlay structure. The name of the program 
section (a 1- to 6-character name consisting of the Radix-50 
characters A-Z, 0-9, and $) and its attributes are given in the .PSECT 
directive. The attributes used in the .PSECT directive must match 
those in the actual program section in the module. Thus, you can use 
the name in a .ROOT or .FCTR statement to indicate to the Task Builder 
the segment to which the program section will be allocated. An 
example of the use of .PSECT is given in the modified version of task 
TKl (the original version is shown in Figure 3-3 in Section 3.1.1) 
shown below. 

In this example, TKl has a disk-resident overlay structure. The 
example assumes that the programmer was careful about the logical 
independence of the modules in the overlay segment, but failed to take 
into account the requirement for logical independence in multiple 
executions of the same overlay segment. 

The flow of task TKl can be summarized as follows. CNTRL calls each 
of the overlay segments, and the overlay segment returns to CNTRL in 
the order A, B, C, A. Module A is executed twice. The overlay 
segment containing A must be reloaded for the second execution. 

Module A uses a common block named DATA3. The Task Builder allocates 
DATA3 to the overlay segment containing A. The first execution of A 
stores some results in DATA3. The second execution of A requires 
these values. in this disk-resident overlay structure, however, the 
values calculated by the first execution of A are overlaid. When the 
segment containing A is read in for the second execution, the common 
block is in its initial state. 

To permit the two executions of A to communicate, a .PSECT directive 
is used to force the allocation of DATA3 into the root. The indirect 
command file for TKl, TFIL.ODL, is modified as follows: 

.PSECT DATA3,RW,GBL,REL,0VR 

. ROOT CNTRL- DATA3- ( AFCTR , BFCTR , C) 
AFCTR: .FCTR A0-(A1,A2-(A21,A22) ) 
BFCTR: .FCTR B0-(B1,B2) 

.END 

The attributes RW, GBL, REL, and OVR are described in Chapter 2. 
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3.4.7 Indirect Command Files 

The Overlay Description Language processor can accept ODL text 
indirectly, that is, specified in an indirect command file. If an at 
sign (@) appears as the first character in an ODL line, the processor 
reads text from the file specified immediately after the at sign. The 
processor accepts the ODL text from the file as input at the point in 
the overlay description where the file is specified. 

For example, suppose you create a file, called BIND. ODL, that contains 
the text: 



B: 



.FCTR B1-(B2,B3) 



A line beginning with (asiND can replace this text at the position 
where the text would have appeared: 

Indirect 



C: 
@BIND 



.ROOT A-(B,C) 
.FCTR C1-(C2,C3) 



• END 
The Task Builder allows two levels of indirection 





Direct 




.ROOT A-(B,C) 


C: 


.FCTR C1-(C2,C3) 


B: 


•FCTR B1-(B2,B3) 




.END 



3.5 MOLTIPLE-TREE STRUCTURES 

You can define more than one tree within an overlay structure. These 
multiple tree structures consist of a main tree and one or more 
co-trees. The root segment of the main tree is loaded by the 
Executive when the task is made active, while segments within each 
CO- tree are loaded through calls to the overlay run-time routines. 
Except for this distinction, all overlay trees have identical 
characteristics: a root segment that resides in memory, and two or 
more overlay segments. 

The main property of a structure containing more than one tree is that 
storage is not shared among trees. Any segment in a tree can be 
referred to from another tree without displacing segments from the 
calling tree. Routines that are called from several main tree overlay 
segments, for example, can overlay one another in a co-tree. The same 
considerations in deciding whether to create memory-resident overlays 
or disk-resident overlays in a single-tree structure apply in building 
a structure containing co-trees. 



3.5.1 Defining a Multiple-Tree Structure 

Multiple-tree structures are specified within the Overlay Description 
Language by extending the function of the comma operator. As 
described in Section 3.4, this operator, when included within 
parentheses, defines a pair of segments that share storage. Including 
the comma operator outside all parentheses delimits overlay trees. 
The first overlay tree thus defined is the main tree. Subsequent 
trees are co-trees. For example: 



X: 
Y: 



ROOT 


X,Y 


FCTR 


X0-(X1,X2,X3) 


FCTR 


Y0-(yi,Y2) 


END 
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In this example, two overlay trees are specified: 1) a main tree 

containing the root segment XO and three overlay segments; and 2) a 

co-tree consisting of root segment YO and two overlay segments. The 
Executive loads segment XO into memory when the task is activated. 

The task then loads the remaining segments through calls to the 
overlay run-time routines. 



3.5.1.1 Defining Co- trees With a Null Root by Osing .NAME - A co-tree 
must have a root segment to establish linkage with its own overlay 
segments. However, co-tree root segments need not contain code or 
data and, therefore, can be length. You can create a segment of 
this type, called a null segm.ent , by means of the .NAME directive. 
The previous example is modified, as shown below, to move file YO.OBJ 
to the root and include a null segment. 



Y: 



The null segment YNUL is created by using the .NAME directive, and 
replaces the co-tree root that formerly contained YO.OBJ. 



3.5.2 Multiple-Tree Example 

The following example illustrates the use of multiple trees to reduce 
the size of the task. 

In this example, the root segment CNTRL of task TKl (described in 
Section 3.1.1) has had two routines added to it: CNTRLX and CNTRLY. 
The routines are logically independent of each other, and both are 
approximately 4000 (octal) bytes long. However, the routines have been 
placed in the root segment of TKl instead of being overlaid because 
both routines must be accessed from modules on all paths of the tree. 
In a single-tree overlay structure, the root segment is the only 
segment common to all paths of the tree. The schematic diagram for 
the modified structure is shown in Figure 3-14. 

A21 A22 



.ROOT 


X,Y 


.FCTR 


X0-Y0-(X1,X2,X3) 


.NAME 


YNUL 


.FCTR 


YNUL-(Y1,Y2) 


.END 





A1 A2 81 B2 



AO BO 



\ 

CNTRLY 



CNTRLX 

I 
CNTRL 



ROOT 
SEGMENT 



ZK-407-81 

Figure 3-14 Overlay Tree for Modified TKl 
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One possible overlay description for this structure is shown below: 

•ROOT CNTRL-CNTRLX-CNTRLY-(AFCTR,BFCTR,C) 
AFCTR: .FCTR AO- ( Al , A2FCTR) 
A2FCTR: .FCTR A2-(A21,A22) 
BFCTR: .FCTR B0-(B1,B2) 

.END 

Because TKl consists of disk-resident overlays and the new routines 
are concatenated within the overlay structure, the new routines add 
10000 (octal) bytes to both the virtual address space and physical 
memory requirements of the task. However, the added routines consume 
more virtual address space than might be expected, as shown in Figure 
3-15. 

The expansion of TKl's virtual address space requirements caused the 
task to extend 4000 (octal) bytes beyond the next highest 4K-word 
boundary (APR 2) . Because the Executive must use an additional 
mapping register (APR2) , the apparent cost in virtual address space 
above APR 2 of 4000 (octal) bytes is in fact 20000 (octal) bytes, 
(Compare the diagram in Figure 3-15 with the diagram in Figure 3-3.) 
The shaded portion of the unused virtual address space in Figure 3-15 
represents the portion of virtual address space that is allocated but 
is unusable as allocated. 

Small tasks, such as TKl, are seldom adversely affected by the 
inefficient allocation of virtual address space, but larger tasks may 
be. For example, a large task that contains code to create dynamic 
regions (see Chapter 5) or that contains Executive directives to 
extend its task region (see the RSX-llM/M-PLUS Executive Reference 
Manual ) requires at least 4K words of virtual address space to map 
each region. in such a task, using co- trees can often save virtual 
address space and can, therefore, be of paramount importance. TKl can 
be modified to reflect this. 

As noted earlier, the routines CNTRLX and CNTRLY are logically 
independent. Logical independence is a primary requirement for all 
segments that overlay each other. However, CNTRLX and CNTRLY cannot 
be structured into either of the main branches of TKl's tree because 
it is further required that the routines be accessible from modules on 
all paths of the tree. Therefore, the only way CNTRLX and CNTRLY can 
be overlaid and still meet all of these requirements is through a 
co-tree structure. Figure 3-16 shows the schematic representation of 
TKl as a CO- tree structure. 

The root segment CNTRL2 of the co-tree is a null segment. It contains 
no code or data and has a length of 0. As noted earlier, the Task 
Builder requires the root segment in order to establish linkage with 
the overlay segments. One possible overlay description for building 
TKl as a 2-tree structure is shown below. 

.NAME CNTRL2 

.ROOT CNTRL-( AFCTR, BFCTR, C) ,CNTRL2- (CNTRLX , CNTRLY) 
AFCTR: .FCTR AO- ( Al , A2FCTR) 
A2FCTR: .FCTR A2-(A21,A22) 
BFCTR: .FCTR B0-(B1,B2) 

.END 

You define the co-tree in the .ROOT directive by placing the comma 
operator outside all parentheses (immediately before CNTRL2) . The 
.NAME directive creates the null root segment. Figure 3-16 shows the 
new relationship between virtual address space and physical memory. 
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APR7- 



APR6- 



APR5- 



APR4- 



APR3- 



APR2- 



UNUSED! 



ROOT 
SEGMENT' 



1 APR1 



^APRO- 




VIRTUAL ADDRESS 
SPACE 



A1 



A21 A22 



A2 



AO 



B1 



B2 



BO 



_CNTRL_Y 
CNTRLX 



CNTRL 



HEADER AND STACK 



PHYSICAL MEMORY 



Figure 3-15 virtual Address Space and Physical Memory 

for Modified TKl 
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A21 A22 



A1 A2 B1 B2 



AO BO C CNTRLX CNTRLY 



CNTRL CNTRL2 

MAIN TREE CO-TREE 

ZK-40g-81 

Figure 3-16 Overlay Co-Tree for Modified TKl 

The diagrams in Figure 3-17 illustrate the savings (4000 (octal) bytes) 
in both virtual address space and physical memory that is realized by 
overlaying CNTRLX and CNTRLY. What may be more important in some 
applications, however, is that the top of TKl's task region has 
dropped below the 4K-word boundary of APR 2. TKl has gained 4K words 
of potentially usable virtual address space. 

NOTE 

The numbers used in this example have 
been simplified for illustrative 
purposes. In addition, the storage 
required for overhead in handling the 
overlay structures is not reflected in 
this example. 

Because the null root CNTRL2 is bytes long, it does not require any 
virtual address space or physical memory and, therefore,' does not 
appear in the diagrams in Figure 3-17. 

Finally, you can define any number of co-trees. Additional co-trees 
can access all modules in the main tree and other co-trees. 
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APR 7- 



APR 6- 



APR5- 



APR 4- 



APR3- 



APR 2- 



APR 1- 



APR 0- 
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A2 
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CNTRLX 



A1 
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A2 
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CNTRLY 



B1 



82 



BO 



CNTRL 
(ROOT SEGMENT) 



HEADER AND STACK 
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Figure 3-17 Virtual Address Space 
and Physical Memory for TKl As a Co-Tree 



3.6 CREATING AH ODL FILE FROM A VIRTUAL ADDRESS SPACE ALLOCATION 
DIAGRAM 

You can use a graphic method as an aid to converting a virtual address 
space allocation diagram into the correct Task Builder ODL file. 
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First create a virtual address space allocation diagram of your 
overlaid task, similar to that shown in Figure 3-18, without the 
dotted-line path shown in the diagram. 



A1 



A21 



A22 



A2 



AO 



B1 



82 



BO 



ROOT (CNTRL) 



ZK-1052-82 

Figure 3-18 virtual Address Space Allocation Diagram 



The dotted-line path will be the basis for writing the ODL statements 
that you need. To determine the path through your virtual address 
space allocation diagram, follow these steps: 

1. Start in the lower left corner of the root segment. 

2. Draw a dotted line upward as far as you can go without 
passing through the top or into "empty" virtual space, 
crossing into new segments as needed. 

3. When you reach the top segment, proceed to the right until 
you reach a vertical line. 

4. If the end of your dotted line is now opposite the vertical 
line of the lowest segment, cross the vertical line and 
continue again from step 2; otherwise, proceed to step 5. 

5. Because the end of your dotted line is not opposite the 
vertical line of the lowest segment proceed downward until 
you reach the lowest segment. 

6. If you are not in the root, cross the vertical line to the 
right and continue from step 2; otherwise, proceed to step 
7. 

7. If your dotted line is in the lower right corner of the root, 
you have finished the dotted-line walk. 
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Once you have drawn the dotted line, you should go back over it to 
verify that you followed all the steps. While doing this, draw 
arrowheads at each point where a line was crossed to indicate the 
direction of the line. 



3.6.1 Creating a .ROOT Statement by Using a Virtual Address Space 
Allocation Diagram 

Now you are ready to write the .ROOT statement. Follow these steps: 

1. Write .ROOT followed by the name of the root statement (in 
this example, .ROOT CNTRL) . 

2. Follow the dotted-line path. 

3. Add each successive ODL element to your root statement, using 
the following syntax, based on the direction of your dotted 
line. 

A. At an upward crossing: -("name of new segment" 

B. At a horizontal crossing: ,"name of new segment" 

C. At a downward crossing: ) 

4. When you have returned to the root, your root statement is 
complete. 

Using the dotted-line path in Figure 3-18 and the above associated 
steps for writing the .ROOT statement, you can write as shown below: 

Write .ROOT CNTRL 

Write .ROOT CNTRL- (AO 

Write .ROOT CNTRL- (A0-{A1 

Write .ROOT CNTRL- (AO- (Al ,A2 

Write .ROOT CNTRL- (AO- (A1,A2- (A21 

Write .ROOT CNTRL- (AO- ( A1,A2- (A21 ,A22 

Write .ROOT CNTRL- (AO- (A1,A2- (A21,A22) 

Write .ROOT CNTRL- (AO- (Al ,A2- (A21 ,A22) ) 

Write .ROOT CNTRL- (AO- (A1,A2- (A21,A22) ), BO 

Write .ROOT CNTRL- (AO- (A1,A2- (A21,A22) ) -BO- (Bl 

Write .ROOT CNTRL- (AO- (A1,A2- (A21 ,A22) ) -BO- (B1,B2 

Write .ROOT CNTRL-(A0-(A1,A2-(A21,A22) )-B0-(Bl,B2) 

Write .ROOT CNTRL- (AO- (Al ,A2- (A21 ,A22) ) -BO- {B1,B2) ,C 

Write .ROOT CNTRL- (AO- (A1,A2- (A21,A22) ) -BO- (B1,B2) ,C) 

The steps for writing .FCTR statements and co-tree statements follow 
next. 
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3.6.2 Creating a .FCTR Statement by Osing a Virtual Address Space 
Allocation Diagram 

By using the steps for creating a .ROOT statement from a virtual 
address space allocation diagram, you created the following .ROOT 
statement. 

.ROOT CNTRL-(A0-{A1,A2-(A21,A22) )-B0-(Bl,B2) ,C) 

It may be desirable to simplify your specific .ROOT statement into one 
or more .FCTR statements. A technique similar to the one used to 
create the .ROOT statement may be used to create the .FCTR statement. 

In this example, segments AO , Al , A2, A21, and A22 are selected to be 
in the .FCTR statement. Having selected these segments (normally 
related as a "stack" of segments) you are now ready to write down the 
.FCTR statement. 

First, draw a virtual address space allocation diagram of the segments 
that you have selected. (You may use Figure 3-18 for this 
explanation.) Then follow these next steps to draw a dotted-line path 
through the diagram: 

1. Start in the lower left corner of the lowest or "base" 
segment (AO) in your diagram. 

2. Draw a dotted line upward as far as you can go without 
passing through the top or into empty virtual space, crossing 
into new segments as needed. 

3. When you reach the top segment, proceed to the right until 
you reach a vertical line. 

4. If the end of your dotted line is now opposite the vertical 
line of the lowest segment, cross the vertical line and 
continue again from step 2; otherwise, proceed to step 5. 

5. Because the end of your dotted line is not opposite the 
vertical line of the lowest segment, proceed downward until 
you reach the lowest segment. 

6. If you are not in the base segment (AO) , cross the vertical 
line to the right and continue from step 2; otherwise, 
proceed to step 7. 

7. If your dotted line is in the lower right corner of the base 
segment, you have finished the dotted-line walk. 

Once you have drawn the dotted line, you should go back over it to 
verify that you followed all the steps. While doing this, draw 
arrowheads at each point where a line was crossed to indicate the 
direction of the line. 

Now you are ready to write the .FCTR statement. Follow these next 
steps: 

1. Write a label followed by .FCTR, which is in turn followed by 
the name of the first segment (AO) (in this example, AFCTR 
•FCTR AO) 

2. Follow the dotted-line path. 
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3. Add each successive ODL element to your root statement, using 
the following syntax, based on the direction of your dotted 
line. 

A. At an upward crossing: ("name of new segment" 

B. At a horizontal crossing: ,"name of new segment" 

C. At a downward crossing: ) 

4. When you have returned to the base segment, your .FCTR 
statement is complete. 

Using the dotted line path and the above associated steps for writing 
the .FCTR statement, you can write as shown below: 

1. Step 1 : Write AFCTR .FCTR AO 

2. Step 3A: Write AFCTR .FCTR A0-{A1 

3. Step 3B: Write AFCTR .FCTR A0-(A1,A2 

4. Step 3A: Write AFCTR .FCTR AO- (A1,A2- (A21 

5. Step 3B: Write AFCTR .FCTR AO- (A1,A2- (A21 ,A22 

6. Step 3C: Write AFCTR .FCTR AO- (A1,A2- (A21,A22) 

7. Step 3C: Write AFCTR .FCTR AO- (AI,A2- (A21 ,A22) ) 

You have now reached the base segment and have written the two ODL 
statements : 

.ROOT CNTRL-(A0-(A1,A2-(A21,A22))-B0-(B1,B2) ,C) 
AFCTR: .FCTR A0-(A1,A2-(A21,A22) ) 

The last step requires that you substitute the label, AFCTR, into the 
.ROOT statement, which results in: 

.ROOT CNTRL-AFCTR-B0-(B1,B2) ,C) 
AFCTR: .FCTR A0-(A1,A2-(A21,A22) ) 

Additional .FCTR statements would be determined and written in the 
same way. For example, you could write a .FCTR statement labeled 
BFCTR for the segments BO, Bl , and B2 . 

The following section shows how to write an ODL statement for a 
co-tree by using the same methods. 



3.6.3 Creating an ODL Statement for a Co-Tree by Using a Virtual 
Address Space Diagram 

Assuming that you want to write an ODL statement for a co-tree like 
the one in Figure 3-19, you would have two virtual address space 
allocation diagrams, one for the main tree and one for the co-tree. 
These two diagrams are shown in Figure 3-19. 
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Figure 3-19 Virtual Address Space Allocation for a Main Tree 

and Its Co-Tree 



From Figure 3-19 you see that the co-tree is a stack of segments also. 
Therefore, it is possible to write the statement for the co-tree in 
the same fashion and with the same rules as that described in Section 
3.6. However, certain facts must be kept in mind. These are that: 

• The co-tree has a null root 

• A .NAME statement must be used to name the null root 

• A comma must be placed outside of the parentheses and at the 
end of that part of the .ROOT statement that defines the main 
tree 

Therefore, the ODL statement that we obtain before writing the co-tree 
part is: 

.NAME CNTRL2 

.ROOT CNTRL-AFCTR-B0-(B1,B2) ,C) , 
AFCTR: .FCTR A0-(A1,A2-(A21,A22) ) 

By following the rules in Section 3.6 and by using the diagram in 
Figure 3-19, you can then create the ODL statement: 

.NAME CNTRL2 

.ROOT CNTRL-AFCTR-B0-(B1,B2) ,CNTRL2- (CNTRLX, CNTRLY) 
AFCTR: .FCTR A0-(A1,A2-(A21,A22)) 



3.7 OVERLAYING PROGRAMS WRITTEN IN A HIGH-LEVEL LANGDAGE 

Programs written in a high-level language usually require the use of a 
large number of library routines in order to execute. Unless care is 
taken when overlaying such programs, the following problems can occur: 

• TKB throughput may be drastically reduced because of the 
number of library references in each overlay segment. 
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Library references from the default object module library that 
are resolved across tree boundaries can result in 
unintentional displacement of segments from memory at run 
time. 

• Attempts to task-build such programs can result in multiple 
and ambiguous symbol definitions when a co-tree structure is 
defined. 

The following procedures are effective in solving these problems: 

• You can increase TKB throughput by linking commonly used 
library routines into the main root segment. 

• YOU can eliminate ambiguous definitions, multiple definitions, 
and cross-tree references by using the NOFU switch (the TKB 
default) to restrict the scope of the default library search. 
However, restricting the scope of the default library search 
may also cause problems. 

If sufficient memory is available, you can effectively place the 
object time system in the root segment by building a memory-resident 
library. This also reduces total system memory requirements if other 
tasks are also currently using the library. 

If a memory-resident library cannot be built, you can force library 
modules into the root by preparing a list of the appropriate global 
references and linking the object module into the root segment. 

For other ways to reduce task size, you should consult the user's 
guide for the language you are using. 



3.8 EXAMPLE 3-1: BDILDING AN OVERLAY 

The text in this section and the figures associated with it illustrate 
the building of an overlay structure. For this example, the routines 
of the resident library LIB.TSK and the task that refers to it, 
MAIN.TSK (from Example 5-3, Chapter 5), are assembled as separate 
modules and built as an overlaid task. This task is built first with 
disk-resident overlays and then with memory-resident overlays. The 
disk-resident version of the task is named OVR.TSK and the 
memory-resident version is named RESOVR.TSK. 



NOTE 

This example is intended to provide you 
with a working illustration of the 
Overlay Description Language. It does 
not reflect the most efficient use of 
it. 

Two alterations were made to each of the routines for this example: 

• A .TITLE and .END assembler directive was added to each 
routine to establish it as a unique module. 
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• The following assembler directive was added to each arithmetic 
routine to increase its allocation: 

.BLKW 1024. *3 

This was done to make TKB allocation of address space more 
obvious for documentation purposes. 

The operation of the overlaid task is identical to that of Example 5-3 
in Chapter 5. The routines and their titles as a result of the .TITLE 
directives are as follows: 

• The integer addition routine is named ADDOV. 

• The integer subtraction routine is named SUBOV. 

• The integer multiplication routine is named MOLOV. 

• The integer division routine is named DIVOV. 

• The register save and restore routine is named SAVOV. 

• The print routine is named PRNOV. 

• The main calling routine is named ROOTM. 
The lengths of the modules are: 

Module Length (in Octal) 

ADDOV 14024 bytes 

SUBOV 14024 bytes 

MULOV 14024 bytes 

DIVOV 14026 bytes 

SAVOV 4042 bytes 

PRNOV 4260 bytes 

ROOTM 4104 bytes 

The flow of control for OVR.TSK is as follows: 

1. ROOTM calls ADDOV and ADDOV returns to ROOTM, 

2. ROOTM calls PRNOV to print the result and PRNOV returns to 
ROOTM. 

3. ROOTM calls SUBOV and SUBOV returns to ROOTM. 

4. ROOTM calls PRNOV to print the result and PRNOV returns to 
ROOTM. 

5. ROOTM calls DIVOV and DIVOV returns to ROOTM. 

6. ROOTM calls PRNOV to print the result and PRNOV returns to 
ROOTM. 
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7. ROOTM calls MULOV and MULOV returns to ROOTM. 

8. ROOTM calls PRNOV to print the result and PRNOV returns to 
ROOTM . 

The print routine (contained in module PRNOV) is called between each 
arithmetic operation by the control routine (contained in module 
ROOTM) . To avoid loading it into physical memory each time it is 
called, you can place PRNOV in the root segment of the task. In 
addition, each arithmetic routine calls SAVOV. Therefore, SAVOV must 
be on a path common to all segments in the tree. It too is placed in 
the root segment of the task. One possible overlay configuration for 
this task is shown in Figure 3-20. 

SUBOV DIVOV 



MULOV ADDOV 



L 



1 

SAVOV 



, ROOT 
PRNOV ( SEGMENT 

ROOTM 



Figure 3-20 Overlay Tree of Virtual Address Space for OVR.TSK 

To build this overlay, first create an ODL file (OVERTREE.ODL) that 
contains its description: 

.ROOT ROOTM-PRNOV-SAVOV-* (MULOV, ADDOV- (SUBOV, DIVOV) ) 
.END 

Then, after you have modified the modules and assembled them, you can 
build the task with the following command line: 

TKB> OVR,OVR/-SP=OVRTREE/MP 

This command instructs TKB to build a task image, OVR.TSK, and to 
create a map file, OVR.MAP, under the UFD that corresponds to the 
terminal UIC. The negated spool switch (/-SP) inhibits TKB from 
spooling the map file to the line printer. 

The overlay switch (/MP) attached to the input file tells TKB that the 
input file is an ODL file. Therefore, this file will be the only 
input file specified. Refer to Chapter 10 for a description of the 
switches used in this example. 

A portion of the map that results from this task build is shown in 
Example 3-1. 
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Example 3-1 Map File for OVR.TSK 



OVR.TSK Memory allocation map TKB M40.10 

Ol-JAN-82 10:06 



Page 1 



Partition name 

Identification 

Task OIC 

Stack limits 

PRG xfr address 

Total address windows: 

Task image size 

Task address limits 

R-W disk blk limits 



GEN 

01 

[7,62] 

000260 001257 001000 00512. 

001264 r~ 

1. © 

7488. words 

000000 035107 

000002 000073 000072 00058. 



OVR.TSK Overlay description: 



Base 

-— 

000000 1 

005034 

005034 

021060 

021060 


Top 

— e 

005033 1 
021057 
021057 h 
035103 
035107 

c 


Leng 


th 


005034 
014024 
014024 
014024 
014030 


02588. 
06164. 
06164. 
06164. 
06168. 



ROOTM 



MULOV 
ADDOV 



SUBOV 
DIVOV 



*** Root segment: ROOTM 

R/W mem limits: 000000 005033 005034 02588. 
Disk blk limits: 000002 000007 000006 00006. 

Memory allocation synopsis: 

Section 



. BLK.:(RW,I,LCL,REL,CON) 001260 002514 01356. 

001260 000102 00066. 

001362 000260 00176. 

001642 000042 00034. 
ANS : (RW,D,GBL,REL,OVR) 003774 000002 00002. 

003774 000002 00002. 

003774 000002 00002. 



Title Ident File 



ROOTM 
PRNOV 
SAVOV 

ROOTM 
PRNOV 



01 
01 
01 

01 
01 



ROOTM. OBJ; 1 
PRNOV. OBJ; 1 
SAVOV. OBJ; 1 

ROOTM. OBJ; 1 
PRNOV. OBJ ;1 



Global symbols; 



AADO 
MOLL 



004032-R 
004022-R 



DIVV 
SAVAL 



004052-R 
001642-R 



PRINT 001550-R SUBB 004042-R 



*** Task builder statistics: 

Total work file references: 6863. 

Work file reads: 0. 

Work file writes: 0. 

Size of core pool: 7086. words (27, 

Size of work file: 3072. words (12, 

Elapsed time:00 :00 :14 



pages) 
pages) 
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Figure 3-21 shows the allocation of virtual address space for OVR.TSK. 
The circled numbers in Example 3-1 correspond to those in Figure 3-21. 

Note that the root segment for OVR.TSK (ROOTM) has expanded with task 
building while the segments containing the arithmetic routines have 
not. Before task building, the sum of the modules (in octal bytes) 
that comprise the root segment is: 

4104 + 4260 + 4042 = 14,426 bytes 

After task building, the root segment is 20,677 (octal) bytes long. 
TKB has added a header, a stack area, and the overlay run-time 
routines to it. The segments containing the arithmetic routines have 
not changed. If there had been calls from segments nearer the root to 
segments farther up the tree, the Task Builder would have added data 
structures to the calling segments as well. (Refer to Chapter 4 for a 
description of the overlay loading methods.) 

You can build OVR as a memory-resident overlay by simply adding the 
memory-resident operator (!) to the ODL file for OVR as shown below: 

.ROOT ROOTM- PRNOV-SAVOV-* ! (MULOV,ADDOV- ! (SUBOV,DIVOV) ) 
.END 

For this example, the name of the ODL file and the task image file 
have been changed to RESOVR.ODL to distinguish it from the 
disk-resident version. You can build RESOVR with the following 
command line: 

TKB> RESOVR, RESOVR/-SP=RESOVR/MP 

This command directs TKB to build a task named RESOVR. TSK and to 
create a map file named RESOVR. MAP. The negated spooling switch 
(/-SP) inhibits spooling of the map file. 

The /MP switch on the input file tells TKB that the file is an ODL 
file and that it will be the only input file for this task build. 
Refer to Chapter 10 for a description of the switches used in this 
example. 

A portion of the map that results from this task build is shown in 
Example 3-2. 

Figure 3-19 shows the allocation of virtual address space for 
RESOVR.TSK. The circled numbers in Example 3-2 correspond to those in 
Figure 3-22. 
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160000 APR 7- 



140000 APR 6- 



120000 APR 5- 



100000 APR 4- 



60000 APR 3- 



40000 APR 2- 



20000 APR 1- 



APR 0- 



! UNUSED! 



MULOV 



SUBOV 



DIVOV 



ADDOV 



SYSLIB 
SAVOV 
PRNOV 
ROOTM 



HEADER AND STACK 



035107 



■021057 



005033 



001257 
000000 



"No 



ROOT SEGMENT 



Figure 3-21 Allocation of Virtual Address Space for OVR.TSK 
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Example 3-2 Map File for RESOVR.TSK 



Partition name 
Identification 
Task UIC 
Stack limits 
PRG xfr address 



GEN 

01 

[7,62] 

000320 001317 001000 00512, 

001324 



V 
Total address windows: 3. © 
Task image size : 13920. words 
Task address limits: 000000 057777 
R-W disk blk limits: 000003 000074 000072 00058, 



RESOVR.TSK Overlay description: 



Base 


Top 


Lena 


th 




--__ O— © -- 


— 




000000 i 005677 1 005700 


03008. 


ROOTM 


020000 034077 014100 


06208. 


MOLOV 


020000 h 


034077 h 


014100 


06208. 


ADDOV 


040000 


054077 


014100 


06208. 


SUBOV 


040000 I 


054077 


014100 


06208. 


DIVOV 



©o o© 



*** Root segment: ROOTM 

R/W mem limits: 000000 005677 005700 03008. 
Disk blk limits: 000003 000010 000006 00006. 



Memory allocation synopsis: 
Section 



BLK. : {RW,I,LCL,REL,CON) 



ANS 



(RW,D,GBL,REL,OVR) 



001320 002514 01356. 

001320 000102 00066. 

001422 000260 00176. 

001702 000042 00034. 

004034 000002 00002. 

004034 000002 00002. 

004034 000002 00002. 



Title Ident File 



ROOTM 
PRNOV 
SAVOV 

ROOTM 
PRNOV 



01 
01 
01 

01 
01 



ROOTM. OBJ; 1 
PRNOV. OBJ ;1 
SAVOV. OBJ; 1 

ROOTM. OBJ; 1 
PRNOV. OBJ ;1 



Global symbols: 

AADD 004072-R DIVV 
MOLL 004062-R SAVAL 



004112-R 
001702-R 



PRINT 001610-R SUBB 



004102-R 



*** Task builder statistics: 



Total work file references; 



6938. 



Work 


file reads : 


0. 








Work 


file writes : 


0. 








Size 


of core pool: 


4178. 


words 


(16. 


pages) 


Size 


of work file: 


3072. 


words 


(12. 


pages) 



Elapsed time:00 :00 :21 
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Note that TKB allocates virtual address space for each level of 
overlay segment on a 4K-word boundary. When built as a disk-resident 
overlay, this structure requires 12K words of virtual address space; 
when built as a memory-resident overlay structure, it requires 16K 
words of virtual address space. As noted earlier, you must be careful 
when using memory-resident overlays to ensure that virtual address 
space is used efficiently. 



160000 APR 7- 



140000 APR 6- 



120000 APR 5- 



100000 APR 4- 



60000 APR 3- 



40000 APR 2- 



20000 APR 1- 



APR 0- 



UNUSED 




SYSLIB 
SAVOV 
PRNOV 
ROOTM 



HEADER AND STACK 



054077 




ROOT SEGMENT 



Figure 3-22 Allocation of virtual Address Space for RESOVR.TSK 
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Finally, note in Figure 3-22 that TKB has allocated three window 
blocks to map RESOVR.TSK. Each level of the overlay in a 
memory- resident overlay requires a separate window block to map it. 
In a disk-resident overlay, a single window block maps the entire 
structure regardless of how many segment levels there are within the 
structure. This consideration can be important when you are building 
an overlaid task that either creates dynamic regions or accesses a 
resident library or common, because of the extra window blocks 
required to use these features. 



3.9 SUMMARY OF THE OVERLAY DESCRIPTION LANGUAGE 



• An overlay structure consists of one or more trees. Each tree 
contains at least one segment. A segment is one or more 
modules containing one or more program sections that can be 
loaded by a single disk access. 

A tree can have only one root segment, but it can have any 
number of overlay segments. 

• An ODL file is a text file consisting of a series of overlay 
description directives, one directive per line. You enter 
this file in the TKB command line, and identify it as an ODL 
file by attaching the MP switch to the file name. If you 
enter an ODL file in the TKB command line, it must be the only 
input file you specify. 

• The Overlay Description Language provides five directives for 
specifying the tree representation of the overlay structure: 

.ROOT and .END — There can be only one .ROOT and one .END 
directive; the .END directive must be the last directive 
because it terminates input. 

.PSECT, .FCTR, and .NAME — These can be used in any order 
in the ODL file. 

• You define the tree structure using the hyphen (-) , comma (,), 
and exclamation point (!) operators, and by using parentheses. 

The hyphen operator (-) indicates that its arguments are to 
be concatenated and thus are to coexist in memory. 

The comma operator {,) within parentheses indicates that 
its arguments are to overlay each other either physically, 
if disk resident, or virtually, if memory resident. 

The comma operator not within parentheses delimits overlay 
trees. 

The exclamation point operator (!) immediately before a 
left parenthesis declares the enclosed segments to be 
memory resident. Nested segments in parentheses are not 
affected by an exclamation point operator at a level closer 
to the root. 
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The parentheses group segments that begin at the same point 
in memory. For example: 

.ROOT A-B-(C,D-(E,F) ) 

This ODL command line defines an overlay structure with a 
root segment consisting of the modules A and B. In this 
structure, there are four overlay segments: C, D, E, and 
F. The outer pair of parentheses indicates that the 
overlay segments C and D start at the same virtual address; 
and similarly, the inner parentheses indicate that E and F 
start at the same virtual address. 

• The .ROOT directive defines the beginning overlay structure. 
The arguments of the .ROOT directive are one or more of the 
following: 

File specifications as described in Chapter 1 

Factor labels 

Segment names 

Program-section names 

• The .END directive terminates input. 

• The .FCTR directive provides a means for replacing text by a 
symbolic reference (the factor label) . This replacement is 
useful for two reasons: 

The .FCTR directive extends the text of the .ROOT directive 
to more than one line and thus allows complex trees to be 
represented . 

The .FCTR directive allows you to write the overlay 
description in a form that makes the structure of the tree 
more apparent. 

For example: 

.ROOT A-(B-(C,D) ,E-(F,G) ,H) 

.END 

Using the .FCTR directive, you can write this overlay 
description as follows: 

.ROOT A-(FI,F2,H) 
Fl: .FCTR B-(C,D) 
F2: .FCTR E-(F,G) 

.END 

The second representation makes it clear that the tree has 
three main branches. 

• The .PSECT directive provides a means for directly specifying 
the segment in which a program section is placed. It accepts 
the name of the program section and its attributes. For 
example : 

.PSECT ALPHA,CON,GBL,RW,I,REL 
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ALPHA is the program section name and the remaining arguments 
are the program section's attributes (program section 
attributes are described in Chapter 2) . 

The program section name (composed of the characters A-Z, 0-9, 
$, or .) must appear first in the .PSECT directive, but the 
attributes can appear in any order or can be omitted. If an 
attribute is omitted, a default condition is assumed. The 
defaults for program section attributes are RW, I, LCL, REL, 
and CON. 

In the example above, therefore, you need only specify the 
attributes that do not correspond to the defaults: .PSECT 

The .NAME directive provides you with the means to designate a 
segment name for use in the overlay description, and to 
specify segment attributes. This directive is useful for 
creating a null segment, naming a segment that is to be loaded 
manually, or naming a nonexecutable segment that is to be 
autoloadable. (Refer to Chapter 4 of this manual for a 
description of manually loaded and automatically loaded 
segments.) If you do not use the .NAME directive, the Task 
Builder uses the name of the first file, program section, or 
library module in the segment to identify the segment. 

The .NAME directive creates a segment name as follows: 

•NAME segname,attr ,attr 

segname 

is the designated name (composed of the characters A-Z, 
0-9, and $) . 



attr 

is an optional attribute taken from the following: GEL, 
NODSK, NOGBL, DSK. 

The defaults are NOGBL and DSK. The defined name must be 
unique with respect to the names of program sections, 
segments, files, and factor labels. 

• you can define a co-tree by specifying an additional tree 
structure in the .ROOT directive. The first overlay tree 
description in the .ROOT directive is the main tree. 
Subsequent overlay descriptions are co-trees. For example: 

.ROOT A-B-(C,D-(E,F)) ,X-(Y,Z) ,Q-(R,S,T) 

The main tree in this example has the root segment consisting 
of files A. OBJ and B.OBJ. Two co-trees are defined; the 
first co-tree has the root segment X and the second co-tree 
has the root segment Q. 
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The RSX-llM/M-PLUS systems provide two methods for loading 
disk-resident and memory-resident overlays: 

• Autoload -- The overlay run-time routines are automatically 
called to load segments you have specified. 

• Manual Load — You include in the task explicit calls to the 
overlay run-time routines. 

When you build an overlaid task, you must decide which one of these 
methods to use, because both cannot be used in the same task. 

The loading process depends on the kind of overlay: 

• Disk resident — A segment is loaded from disk into a shared 
area of physical memory, writing over whatever was present, 

• Memory resident — A segment is loaded by mapping a set of 
shared virtual addresses to a unique unshared area of physical 
memory, where the segment has been made permanently resident 
(after having been initially brought in from the disk) . 

With the autoload method, the overlay run-time routines handle loading 
and error recovery. Overlays are automatically loaded by being 
referenced through a transfer-of-control instruction {CALL, JMP, or 
JSR) . No explicit calls to the overlay run-time routines are needed. 

In the manual load method, you handle loading and error recovery 
explicitly. Manual loading saves space and gives you full control 
over the loading process, including the ability to specify whether 
loading is to be done synchronously or asynchronously. 

In the manual load method, you must provide for loading the overlay 
segments of the main tree, as well as the root segments and the 
overlay segments of the co-trees. Once loaded, the root segment of a 
co-tree remains in memory. 



4 . 1 AUTOLOAD 

To specify the autoload method, you use the autoload indicator, an 
asterisk (*) . You place this indicator in the ODL description of the 
task at the points where loading must occur. The execution of a 
transfer-of-control instruction to an autoloadable segment up-tree 
(farther away from the root) initiates the autoload process. 
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4.1.1 Autoload Indicator 

The autoload indicator (*) marks as autoloadable the segment or other 
task element (as defined below) . If you apply the autoload indicator 
to an DDL statement enclosed in parentheses, every task element within 
the parentheses is marked as autoloadable. Placing the autoload 
indicator at the outermost level of parentheses in the DDL description 
marks every module in the overlay segments as autoloadable. 

In the TKl example of Chapter 3, Section 3.1.1, if segment C consisted 
of a set of modules CI, C2, C3 , C4 , and C5, the tree diagram would be 
as shown in Figure 4-1. 



A21 A22 
1 1 


B1 

1 


B2 
1 


05 


1 

J A2 
1 1 


C4 
03 


1 

AO 

1 


I 
BO 

1 




02 
01 

I 




1 
CNTRL 




ZK-4 13-81 



Figure 4-1 Details of Segment C of TKl 



Placing the autoload indicator at the outermost level of parentheses 

ensures that, regardless of the flow of control within the task, a 

module will be properly loaded when it is called. The DDL description 
for task TKl would be: 





.ROOT 


AFCTR: 


.FCTR 


BFCTR: 


.FCTR 


CFCTR: 


.FCTR 




.END 



CNTRL-* (AFCTR, BFCTR, CFCTR) 
A0-(A1,A2-(A21,A22)) 
B0-(B1,B2) 
C1-C2-C3-C4-C5 



When you use autoload, the root of a co-tree is loaded by path loading 
if one of the branches of the co-tree is called before the root. 
However, if the root of the co-tree is called before the branch is 
called, the root must have an autoload indicator. 

Also, when the root segment of a co-tree is not a null segment, you 
must mark the co-tree's root segment (CNTRL2) as well as its outermost 
level of parentheses to ensure that all modules of the co-tree are 
properly loaded. For example, if the co-tree root (CNTRL2) of the 
multiple tree example. Section 3.5.2, had contained code or data, it 
would have been marked as follows: 

.ROOT CNTRL-* (AFCTR, BFTCR, CFCTR) ,*CNTRL2-* (CNTRLX ,CNTRLY) 



You can apply the autoload indicator to the following elements: 



File names — to make all the components of 
autoloadable. 



the 



file 



Portions of ODL tree descriptions enclosed in 
parentheses — to make all the elements within the parentheses 
autoloadable, including elements within any nested 
parentheses. 
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• Program section names — to make the program section 
autoloadable. The program section must have the instruction 
(I) attribute. 

• Segment names defined by the .NAME directive — to make all 
components of the segment autoloadable. 

• .FCTR label names -- to make the first component of the factor 
autoloadable. All elements specified in the .FCTR statement 
are autoloadable if they are enclosed in parentheses. 

In the following example, two .PSECT directives and a .NAME directive 
are introduced into the DDL description for TKl . Autoload indicators 
are applied as follows: 

.ROOT CNTRL-(*AFCTR,*BFCTR,*CFCTR) O 
AFCTR: .FCTR A0-*ASUB1-ASUB2-*(A1,A2-(A21,A22) ) QQ 
BFCTR: .FCTR {B0-(B1,B2)) 
CFCTR: .FCTR CNAM-C1-C2-C3-C4-C5 

.NAME CNAM,GBL Q 

.PSECT ASUB1,I,GBL,0VR Q 

.PSECT ASUB2,I,GBL,0VR 

.END 

The following notes are keyed to the example above. 

O The autoload indicator is applied to each factor name; 
therefore: 

a. *AFCTR=*AO 

b. *BFCTR=*(B0-(B1,B2) ) 
C. *CFCTR=*CNAM 

CNAM, however, is an element defined by a .NAME directive. 
Therefore, all components of the segment to which the name 
applies are made autoloadable, that is, CI, C2, C3, C4 , and 
C5 . 

© The autoload indicator is applied to the name of a program 
section with the instruction (i) attribute (*ASUB1) , so that 
program section ASUBl is made autoloadable. 

Q The autoload indicator is applied to a portion of the ODL 
description enclosed in parentheses: 

*(A1,A2-{A21,A22)) 

Thus, every element within the parentheses is made 
autoloadable (that is, files Al, A2, A21, and A22) . 

The net effect of this ODL description is to make every element except 
program section ASUB2 autoloadable. 



4.1.2 Path Loading 

The autoload method uses path loading; that is, a call from one 
segment to another segment up- tree (farther away from the root) 
ensures that all the segments on the path from the calling segment to 
the called segment will reside in physical memory and be mapped. Path 
loading is confined to the tree in which the called segment resides. 
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A call from a segment in one tree to a segment in another tree results 
in the loading of all segments on the path in the second tree from the 
root to the called module. 

In Figure 4-2, if CNTRL calls A22, all the modules between the CNTRL 
and A2 are loaded. In this case, modules AO and A2 are loaded. 



A21 
L_ 



A22 
I 



A1 



A2 
_J 



B1 



B2 
_J 



AO 



BO 



C5 
C4 
C3 
C2 
CI 



CNTRL 



ZK-414-81 



Figure 4-2 Path-Loading Example 

With the autoload method, the overlay run-time routines keep a record 
of the segments that are loaded and mapped, and issue disk-load 
requests only for segments that are not in memory. If CNTRL calls A2 
after calling Al, AO is not loaded again because it is already in 
memory and mapped. 



A reference from one segment to another segment down-tree (closer to 
the root) is resolved directly. For example, A2 can immediately 
access AO because AO was path loaded in the call to A2. 



4.1.3 Autoload Vectors 

To resolve a reference up-tree to a global symbol in an autoloadable 

segment, TKB generates an autoload vector for the referenced global 

symbol. The reference in the code is changed to a definition that 
points to an autoload vector entry. The format for the autoload 

vector for conventional tasks is shown in Figure 4-3 and the format 
for I- and D-space tasks is shown in Figure 4-4. 



JSR PC,@.NAUTO 



PC RELATIVE OFFSET TO .NAUTO 



SEGMENT DESCRIPTOR ADDR. 



ENTRY POINT ADDRESS 



Figure 4-3 Autoload Vector Format for Conventional Tasks 

■Fbr/I-; and ,p- space tasks, TKB generates the autoload vector in,,/ a. 
format that differs from the vector in a conventional task. The I- • 

..and D-space autoload vector is six words long and consists, ,_ of „two 

parts: one part residing in I-space and the other part residing in 

D-space, The I-space part consists of two 2-word instructions, and 

the D-space part consists of two words of data. The data m .^he,, 

,,^s.__ i.i__ „„„~««4- A^c^i^ i r^i-r^y arir^roGc: and thp taroet entrv point 

VeCCUX. ciX-fci Lilt:; ot=:yiLtdiu v^^.^v-i-J-t''-^*- «--^'-*^— « _-- -■ 

address. The I- and D-space vector is shown in Figure 4-4. 
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The task riaot and the overlay segments may contain, autoload vectors; 
the r-space part of the root or segment contains the I-space part of 
the, vectors, 'and the D- space part of the root or segment contains the 
Dr-space part of the vectors. 

The MOV instruction in the I-space part of the vector places the 
address- of the D- space part of the vector on the stack. The second 
l,nstructiph in the vector executes an indirect JMP ±o $AOTO through 
the location .NAUTO. 



MOV (PC)+,-(SP) 



ADDRESS OF PACKET (D-SPACE) 



JMP O.NAUTO 



PC RELATIVE OFFSET TO NAUTO 



I-SPACE PORTION 



ADDRESS OF SEGMENT DESCRIPTOR 



ENTRY POINT ADDRESS 



D-SPACE PORTION 

ZK-1 089-82 

'Figcire'4-'4 Autoload vector Format for- I- and D-space Tasks 

In Figures 4-3 and 4-4, a transf er-of-control instruction to the 
up-tree global symbol generates an autoload vector in the shown 
format. An example of the code sequence used in a call to a global 
symbol in an autoloadable segment is shown in Figure 4-5. 



USER TASK ROOT 



CALL GLOBAL 
► • 



AUTOLOAD VECTOR 

JSR PC,@. NAUTO 

SEGMENT DESCRIPTOR ADDRESS 

ENTRY POINT ADDRESS (GLOBAL) 



USER TASK SEGMENT 
GLOBAL:: • -♦- 



i 



$AUTO AUTOLOAD ROUTINE 



$AUTO: 



JMP GLOBAL 



;LOAD 
;SEGMENT 

GOTO 
GLOBAL IN 
SEGMENT 



RETURN 



Figure 4-5 Example Autoload Code Sequence for a Conventional Task 
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An exception to the procedure for generating autoload vectors is made 
in the case of a program section with the data (D) attribute. 
References from a segment to a global symbol up-tree in a program 
section with the data (D) attribute are resolved directly. 

Because TKB can obtain no information about the flow of control within 
the task, it often generates more autoload vectors than are necessary. 
However, your knowledge of the flow of control within your task, and 
of path loading, can help you determine where to place the autoload 
indicators. By placing the autoload indicators only at the points 
where loading is actually required, you can minimize the number of 
autoload vectors generated for the task. 

In the following example, all the calls to overlays originate in the 
root segment. That is, no module in an overlay segment calls outside 
its segment. The root segment CNTRL has the following contents: 

PROGRAM CNTRL 
CALL Al 
CALL A21 
CALL A2 
CALL AO 
CALL A22 
CALL BO 
CALL Bl 
CALL B2 
CALL CI 
CALL C2 
CALL C3 
CALL C4 
CALL C5 
END 

If you place the autoload indicator at the outermost level of 
parentheses, 13 autoload vectors are generated for this task; 
however, because A2 and AO are loaded by path loading to A21, the 
autoload vectors for A2 and AO are unnecessary. Moreover, because the 
call to CI loads the segment that contains C2, C3 , C4 , and C5, 
autoload vectors for C2 through C5 are unnecessary. 

You can eliminate the unnecessary autoload vectors by placing the 
autoload indicator only at the points where explicit loading is 
required, as follows: 

.ROOT CNTRL- (AFCTR,*BFCTR,CFCTR) 
AFCTR: .FCTR AO- (*A1 ,A2-* ( A21 , A22) ) 
BFCTR: .FCTR (B0-(B1,B2)) 
CFCTR: .FCTR *C1-C2-C3-C4-C5 

.END 

With this ODL description, TKB generates seven autoload vectors — for 
Al, A21, A22, BO, Bl, B2, and CI. 
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4.1.4 Autoloadable Data Segments 

You can make overlay segments that contain no executable code 
autoloadable, as follows. First, you must include a .NAME directive 
and specify the GBL attribute, as described in Section 3.4.4. For 
example: 

.ROOT A-*(B,C) 
.NAME BNAME,GBL 
B: .FCTR BNAME-BFIL 
.END 

The global symbol BNAME is created and entered into the symbol table 
of segment BNAME. Because this segment is marked to be autoloaded, 
root segment A calls segment BNAME as follows: 

CALL BNAME 

The segment is autoloaded and an immediate return to inline code 
occurs . 

The data of BFIL must be placed in a program section with the data (D) 
attribute to suppress the creation of autoload vectors. 



4.2 MANUAL LOAD 

If you decide to use the manual-load method to load segments, you must 
include in your program explicit calls to the $LOAD routine. These 
load requests must supply the name of the segment to be loaded. In 
addition, they can include information necessary to perform 
asynchronous load requests, and to handle load request failures. 

The $LOAD routine does not path load. A call to $LOAD loads only the 
segment named in the request. The segment is read in from disk and 
mapped. For memory-resident overlays; the segment is mapped, but 
only read in if it was not previously read in. 

A MACRO-11 programmer calls the $LOAD routine directly. A FORTRAN 
programmer calls $LOAD using the FORTRAN subroutine MNLOAD. 



4.2.1 MACRO-11 Manual Load Calling Sequence 

A MACRO-11 programmer calls $LOAD as follows: 

MOV #PBLK,RO 
CALL $LOAD 

PBLK is the address of a parameter block with the following format: 

PBLK: .BYTE length , event-flag 
.RAD50 /seg-name/ 
.WORD [i/o-status] or 
.WORD [ast-trp] or 



The length of the parameter block (3 to 5 words) 
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event-flag 



The event flag number, used for asynchronous loading. If the 
event-flag number is 0, synchronous loading is performed. 



seg-name 



The name of the segment to be loaded: a 1- to 6-character 
Radix-50 name, occupying two words. 



i/o-status 



The address of the I/O status doubleword. Standard QIO status 
codes apply. 



ast-trp 

The address of an asynchronous trap service routine to which 
control is transferred at the completion of the load request. 

The condition code C-list is set or cleared on return, as 
follows: 

• If condition code C=0, the load request was accepted. 

• If condition code C=l, the load request was unsuccessful. 

For a synchronous load request, the return of the condition code C=0 
means that the desired segment is loaded and is ready to be executed. 
For an asynchronous load request, the return of the code C=0 means 
that the load request was successfully queued to the device driver, 
but the segment is not necessarily in memory. Your program must 
ensure that loading has been completed by waiting for the specified 
event flag before calling any routines or accessing any data in the 
segment. 



4.2.2 MACRO-11 Manual Load Calling Sequence For I- and D-Space Tasks 

A MACRO-11 programmer calls $LOAD as follows: 

MOV #PBLK,RO 
CALL $LOAD 

PBLK is the address of a parameter block with the following format in 
an I- and D-space task: 

PBLK: BYTE 3,0 

.RAD50 /seg-name/ 

length 

The length of the parameter block (3 words) . 
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event- flag 



Specify this as . Only synchronous load requests are possible 
when loading I- and D- space segments. 



seg-name 

The name of the segment to be loaded: a 1- to 6-character 
Radix-50 name, occupying two words. 

The condition code C-list is set or cleared on return, as follows: ' 

■ • If condition code C=0, the load request was accepted. - 

• ' I,f . condition code C=l, the load request was unsuccessful. 

For a .synchronous load request, which is the only one possible: .for .I-- 
and D-space segments, the return of the condition code ■ C=Ov means that 
the desired segment is loaded and is ready to be executed . Youi: 
program, must ensure that loading has been successful by checking -for 
the condition code rather than assuming that the segment ' h-as' beeii 
loaded. " ' ' " ' ' .' \ ' 



4.2.3 FORTRAN Manual Load Calling Sequence 

TO use the manual load mechanism in a FORTRAN program, your program 
must refer to the $LOAD routine by means of the MNLOAD subroutine. 
The subroutine call has the form: 

CALL MNLOAD (seg-name, [event-flag] , [ i/o-status] , [ast-trp] , [Id-ind] ) 
seg-name 

A 2-word real variable containing the segment name in Radix-50 
format. 



event-flag 

An optional integer event flag number used for an asynchronous 
load request. If the event flag number is 0, the load request is 
synchronous . 

i/o-status 

An optional 2-word integer array containing the I/O status 
doubleword, as described for the QIO directive in the 
RSX-llM/M-PLUS Executive Reference Manual. 

ast-trp 

An optional asynchronous trap subroutine entered at the 
completion of a request. MNLOAD requires that all pending traps 
specify' the same subroutines 
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Id-ind 

An optional integer variable containing the results of the 
subroutine call. One of the following values is returned: 

+1 Request was successfully executed. 

-1 Request had bad parameters or was not successfully 
executed. 

You can omit optional arguments. The following calls are legal: 



Call 



Effect 



CALL MNLOAD (SEGAl) 



Loads segment named 
SEGAl synchronously. 



in 



CALL MNLOAD (SEGAl ,0 ,,, LDIND) 



Loads segment named in 
SEGAl synchronously and 
returns success indica- 
tor to LDIND. 



CALL MNLOAD (SEGAl , 1, IOSTAT,ASTSOB, LDIND) 

Loads segment named in 
SEGAl asynchronously, 
transferring control to 
ASTSUB upon completion 
of the load request; 
stores the I/O status 
doubleword in lOSTAT 
and the success 
indicator in LDIND. 

The following example uses the program CNTRL, previously discussed in 
Section 4.1. In this example, there is sufficient processing between 
the calls to the overlay segments to make asynchronous loading 
effective. The autoload indicators are removed from the ODL 
description and the FORTRAN programs are recompiled with explicit 
calls to the MNLOAD subroutine, as follows: 



PROGRAM CNTRL 
EXTERNAL ASTSUB 
DATA SEGAl /6RA1 / 
DATA SEGA21 /6RA21 / 



CALL MNLOAD ( SEGAl , 1 , lOSTAT , ASTSUB, LDIND) 



CALL Al 



CALL MNLOAD (SEGA21 , 1 , lOSTAT , ASTSUB , LDIND) 
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CALL A21 



END 

SUBROUTINE ASTSUB 

DIMENSION I0STAT(2) 



END 



When the AST trap routine is used, the I/O status doubleword is 
automatically supplied to the dummy variable lOSTAT. 



4.2.4 FORTRAN Manual Load Calling Sequence for I- and D-Space Tasks 

To use the manual load mechanism in a FORTRAN program, your program 
must refer to the $LOAD routine by means of the MNLOAD subroutine. 
The subroutine call has the form: 

CALL MNLOAD (seg- name, , , , [Id-ind] ) 

seg-name 

A 2-word real variable containing the segment name in Radix-50 
format. 

Id-ind 

An optional integer variable containing the results of the 
subroutine call. One of the following values is returned: 

+1 Request was successfully executed. 

-1 Request had bad parameters or was not successfully 
executed. 

YOU can omit optional arguments. The following calls are legal: 

Call Effect 

CALL MNLOAD (SEGBl) Loads segment named in SEGBl 

,■■.•■...".;■.- \ ■ .synchrqnoujsl.y...- ■■.•■■/ /.. 

■] /CALL MNLOAD (SEGBl ,>>VLpIND), v .'Loads' segment /named , /: in-/ -SEGBl 

• synchronously and .returns success' 
. indicator to' LDIND. / ; / ' '/• ^' 

Only synchronous loading is possible when manually loading 1- and 
D-space task segments. 



4.3 ERROR HANDLING 

If you use the autoload mechanism, a simple recovery procedure is 
provided that checks the Directive Status Word (D3W) for an error 
indication. If the DSW indicates that no system dynamic storage is 
available, the routine issues a Wait for Significant Event directive 
and tries again; if the problem is not dynamic storage, the recovery 
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procedure generates a synchronous breakpoint trap. If the task 
services the trap and returns without altering the state of the 
program, the request will be retried. 

If you select the manual-load method, you must provide error handling 
routines that diagnose load errors and provide appropriate recovery. 
A more comprehensive user-written error recovery subroutine can be 
substituted for the system-provided routine if the following 
conventions are observed: 



• The error recovery routine must 
$ALERR. 



have the entry point name 



• The contents of all registers must be saved and restored. 

On entry to $ALERR, R2 contains the address of the segment descriptor 
that could not be loaded. Before recovery action can be taken, the 
routine must determine the cause of the error by examining the 
following words in the sequence indicated: 

1. $DSW The Directive Status Word may contain an error 

status code, indicating that the Executive 
rejected the I/O request to load the overlay 
segment. 

2. N.OVPT The contents of this location, offset by N.IOST, 

point to a 2-word I/O status block containing the 
results of the load overlay request returned by 
the device driver. The status code occupies the 
low-order byte of word 0. For example, for a 
device-not-ready condition, the code will be 
lE.DNR. (For more information on these codes, 
refer to the IAS/RSX-11 I/O Operations Reference 
Manual .) 



4.4 GLOBAL CROSS-REFERENCE OF AN OVERLAID TASK 

This section illustrates a global cross-reference that has been 
created for an overlaid task. The task consists of a root segment 
containing the module ROOT. OBJ, and overlay segments composed of 
modules OVRl, 0VR2, 0VR3 , and 0VR4 . The overlay description of the 
file is as follows: 



. ROOT ROOT- ( OVR , * 0VR2 ) 
OVR: .FCTR 0VR1-* (OVR3,OVR4) 

Only segments 0VR2, 0VR3, and 0VR4 are autoloadable. 
the resulting overlay tree. 



Figure 4-6 shows 



*0VR3 



0VR1 
|_ 



•0VR4 



*OVR2 

_l 



ROOT: 



CALL 0VR3 
CALL 0VR1 
CALL 0VR2 



ROOT 



Figure 4-6 Autoload Overlay Tree Example 
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As Shown, the global symbol OVRl is defined in module OVRl, and a 
single nonautoloadable, up-tree reference is made to this symbol by 
the module ROOT, as indicated by the circumflex. Note that because 
OVRl is not autoloadable, it depends on a call to 0VR3 or 0VR4 to get 
loaded by path loading. The asterisk indicates that the module 
contains an autoloadable definition. The modules shown with the 
asterisk define the symbol. 

The asterisks preceding the modules 0VR2 , 0VR3 , and 0VR4 indicate that 
the global symbols 0VR2 , 0VR3 , and 0VR4 are autoload symbols and are 
referenced from the module ROOT through an autoload vector, as shown 
by the at-sign (@) character. 

The asterisk and at-sign are shown in the cross-reference listing in 
Example 4-1. 

Examole 4-1 Cross-Ref erence Listing of Overlaid Task 



OVRTST 



CREATED BY 



TKB 



GLOBAL CROSS REFERENCE 



ON 27-JUL-82 AT 12:04 



PAGE 1 
CREF vol 



SYMBOL 


VALUE 


REFERENCES. 


» • • 




N.ALER 


000010 




AUTO 


# 


OVRES 




N.IOST 


000004 




OVCTL 


# 


OVRES 




N.MRKS 


000016 


# 


OVRES 








N.OVLY 


000000 




OVCTL 


# 


OVRES 




N . OVPT 


000054 




AUTO 




OVCTL 


# VCTDF 


N.RDSG 


000014 


# 


OVRES 








N.STBL 


000002 


# 


OVRES 








N.SZSG 


000012 


# 


OVRES 








OVRl 


002014-R 


# 


OVRl 


" 


ROOT 




0VR2 


002014-R 


* 


0VR2 


(§ 


ROOT 




0VR3 


002014-R 


* 


0VR3 


@ 


ROOT 




0VR4 


002014-R 


* 


0VR4 


@ 


ROOT 




ROOT 


001176-R 


# 


ROOT 








$ALBP1 


001320-R 


# 


AUTO 






1 


$ALBP2 


001416-R 


# 


AUTO 








$ALERR 


001246-R 


# 


ALERR 




OVDAT 




$AUTO 


001302-R 


# 


AUTO 








$DSW 


000046 




ALERR 


# 


VCTDF 




$MARKS 


001546-R 


# 


OVCTL 








$OTSV 


000052 


# 


VCTDF 








$SAVRG 


001452-R 




AUTO 


# 


SAVRG 




$VEXT 


000056 


# 


VCTDF 








.FSRPT 


000050 


# 


VCTDF 








.NALER 


001442-R 


# 


OVDAT 








.NIOST 


001436-R 


# 


OVDAT 








.NMRKS 


001450-R 


# 


OVDAT 








. NOVLY 


001432-R 


# 


OVDAT 








.NOVPT 


000042 


# 


OVDAT 








.NRDSG 


001446-R 


# 


OVDAT 








.NSTBL 


001434-R 


# 


OVDAT 








.NSZSG 


001444-R 


# 


OVDAT 
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Example 4-1 (Cont.) Cross-Ref erence Listing of Overlaid Task 

OVRTST CREATED BY TKB ON 27-JUL-82 AT 12:04 PAGE 2 
SEGMENT CROSS REFERENCE CREF VOl 

SEGMENT NAME RESIDENT MODULES 



OVRl 
0VR2 
0VR3 
0VR4 



OVRl 
0VR2 
0VR3 
0VR4 



ROOT ALERR AUTO OVCTL CVDAT OVRES ROOT SAVRG 

VCTDF 

Down-tree references to the global symbol ROOT are made from modules 
OVRl, 0VR2, 0VR3, and 0VR4. These references are resolved directly. 

The segment cross-reference shows the segment name and modules in each 
overlay. 



4.5 USE AND SIZE OF OVERLAY RUNTIME ROUTINES 

TKB, when constructing an overlaid task, incorporates certain modules 
from the system library to perform the actual overlay operations. An 
overlay run-time routine in the task loads overlays from disk or maps 
resident overlays by issuing QIO$ or CRAW$ directives. 



The modules and routines described below implement the TKB 
mechanism as described in Section 4.1. 



autoload 



There are three major components to the autoload service, as follows: 

AUTO This module controls the overlay process, and the 
autoload vecors indirectly call AUTO through .NAUTO. 
AUTO determines whether the referenced overlay segment 
is already in memory or mapped. It then jumps to the 
required entry point if the entry point is available. 

The AUTO module is supplied in two variations. These 
variations are separately named and described as 
follows: 



AUTO 



AUTOT 



Selected by TKB by default for all overlaid 
tasks. It manages disk-only, PLAS, and cluster 
library overlay structures. 

Manually selected by you by using an explicit 
reference in the TKB .ODL file, as shown below. 
This module disables the AST traps while 
manipulating the overlay data structures. This 
is required where user task AST traps might 
cause modification of the overlay database. To 
Incorporate this module in your task image, you 
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must include the following element in the 
factor of the task's DDL file: 



• ROOT 



-LB: [1,1]SYSLIB/LB:AUT0T- 

In addition to including AUTOT in the .ROOT 
factor, the following code must be included in 
your task as initialization prior to the AST 
handling routines in your task: 

MOV @#.NOVPT,R0 
BISB #200,N.FAST(R0) 

MRKS This routine traverses the overlay descriptor data 
structure to mark any overlay segment that will be 
displaced by a new overlay as "out of memory" and 
consequently not available. 

RDSG The AUTO module calls the RDSG routine repeatedly to 
read or map each segment along the overlay tree path 
into the task's virtual address space. This is referred 
to as "path loading." When path loading is completed, 
AUTO calls the required entry point. 

Several versions of each component exist reflecting the various sizes 
as appropriate for tasks having disk-only overlays, PLAS mapped 
overlays, and/or cluster libraries. TKB incorporates the smallest 
support routines appropriate for the overlay structure of your task. 

Depending on whether your task has disk-only overlays, resident 
overlays, or cluster libraries, TKB forces one of the following 
modules into your task: 

OVCTL Contain the MRKS and RDSG routines optimized for disk 
OVIDL overlays only. No support is included for 
memory-resident or cluster overlays. OVCTL is the 
module included for conventional tasks, and ti3Wi-i[|;;*'*.£K.''t* 

-MoytJlief'ilttclK^^ for l^:-aTid'p-s^C:&-^f.c^Hs-i 

OVCTR Contain MRKS and RDSG routines assembled for disk and 

*|5^i5| memory resident overlays. TKB selects either of these 

modules if the task overlay structure includes 

memory- resident overlays or maps a resident library 

containing resident overlays. OVCTR is the module 

selected for conventional tasks and /;tpiph-overlald I- >^ 

':jQs§agj^^-.fX^sfi&i ■ ' :'' &f^ ■'.'■niodule selected Jfp-r 

^WpiC|ia^pS;;;|Jr'%g3: iT^spafcejtasK^i-' " ■■'■"'■ - 

OVCTC Contain the MRKS, RDSG, and cluster library support 
qVI-DC routines. TKB includes OVCTC or OVIDC if cluster 
libraries are included in your task. OVCTC is the 
module selected for conventional tasks and non-overlaid 
I- and D-space tasks. OVIDC is the module selected for 
overlaid I- and D-space tasks. 
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Two other modules are incorporated into your task's image. They are: 

OVDAT A small, impure data area used by AUTO, MRKS, and RDSG 
routines. TKB includes OVDAT in all overlaid tasks, and 
its size is independent of the overlay structure of that 
task. 

ALERR An error service module that AUTO invokes under one of 
the following circumstances: 

• If an I/O error occurs while attempting to read a 
disk overlay into memory 

• If a directive error occurs while attempting to 
attach or map a region containing memory resident 
overlays 

Table 4-1 compares the sizes of the overlay run-time support modules. 
You can use it to determine when it is appropriate to force certain 
variants into your task image. 

Table 4-1 
Comparison of Overlay Run-Time Module Sizes 



Module 



Program 
Section 



Number 
of Bytes 
Oct/Dec 



Specific Use 



One of the following modules is included in any overlaid task 
that uses autoload and in any task that links to a PLAS overlaid 
resident library. 



AUTO 
AUTOT 



$$AUTO 122/82, 



$$AUTO 

$$RTQ 

$$RTR 



132/90. 
32/26. 
30/24. 



All tasks that use autoload 

All tasks with ASTs 
disabled during autoload 



One of the following modules is included in any overlaid 
conventional task. OVCTR or OVCTC is included in any 
non-overlaid task (conventional or I- and D- space) that links 
to a PLAS overlaid resident library. 



OVCTL 



$$MRKS 76/62. 
$$RDSG 160/112. 
$$PDLS 2/2. 



Disk overlays only 



OVCTR 



OVCTC 



$$MRKS 
$$RDSG 
$$PDLS 

$$MRKS 
$$RDSG 
$$PDLS 



234/156, 

332/218, 

12/10. 

254/172, 
352/234, 
120/80. 



Disk and PLAS overlays with no 
cluster libraries 



Disk and PLAS overlays 
with cluster libraries 



(continued on next page) 
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Table 4-1 (Cont.) 
Comparison of Overlay Run-Time Module Sizes 



Number 
Program of Bytes 
Module Section Oct/Dec Specific Use 

''>:::- -<:::;; '--:i?jrd§g; ^::!?24/i?*.-;:; -;:d'"'--C">- -<::•• v-.::::::;- c:::^.Ji2::''''>'-^:::jy>^ 

'y <.;■■'-- C::z'$'$mi^&'S':*rs^-2i^j^si^^:' ■ .;s|i*fe;^i«'a£eT>a;:i;bif •'- .C!:"->-r 

••-'•-Hd::-'--<i-: -.$$j>e£s..- r-imfM^-T'-Z:^ '^::- •••--.,';::■ •••■■-• ■.::;:• '■^7:::~'->^-.:Z::''r--'^^ "--i:;;:''- 



The overlay data vector OVDAT is included in any overlaid task 
and in any task that links to a PLAS overlaid resident library. 

OVDAT 



$$OVDT 


24/20. 


Included in all tasks 


$$SGDO 


0/0. 


that perform overlay 


$$SGD2 


2/2. 


operations 


$$RTQ 


0/0. 




$$RTR 


0/0. 




$$RTS 


2/2. 





The overlay error service routine ALERR is included whenever 
OVDAT is included. 



ALERR $$ALER 24/20. Overlay error 



Manual overlay control (LOAD) is used in place of any AUTO 
routine. (See Section 4.2, Manual Load.) 

LOAD $$LOAD 252/170. Manual overlay control 
$$AUTO 14/12. 
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CHAPTER 5 
SHARED REGION CONCEPTS AND EXAMPLES 



The Task Builder provides you with many ways of using shared regions 
for tailoring your tasks to meet your specific requirements. This 
chapter describes some of these facilities and their applications. 

This chapter contains five working examples. The discussion of the 
examples assumes that you are familiar with the programming concepts 
described in the RSX-llM/M-PLUS Guide to Program Development and with 
the first four chapters of this manual. 



5.1 SHARED REGIONS DEFINED 

A shared region is a block of data or code that resides in memory and 
can be used by any number of tasks. A shared region can contain data 
for use by several tasks or it may be an area where one task writes 
data for use by another task. Also, a shared region can contain 
routines for use by several tasks. 

Shared regions are useful because they make more efficient use of 
physical memory. The two kinds of shared regions are: 

• A resident common that provides a way that two or more tasks 
can share their data 

• A resident library that provides a way that two or more tasks 
can share a single copy of commonly used subroutines 

The term "resident" denotes a shared region that is built and 
installed into the system separately from the task that links to it. 
In other words, you use TKB to build a shared region much as you would 
use it to build a task. However, the region does not have a header or 
a stack. Also, you can use switches to designate the kind of shared 
region (a library or a common) to be built. 

Figure 5-1 shows a typical resident common. Task A stores some 
results in resident common S, and Task B retrieves the data from the 
common at a later time. 

Figure 5-2 shows a typical resident library. In this case, common 
reentrant subroutines are not included in each task image; instead, a 
single copy is shared by all tasks. 
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PARTITION BOUNDARY 



PARTITION BOUNDARY 





RESIDENT COMMON 
S 










TASK A 




Wi§M^^MMiM!M§m 




EXECUTIVE 




TASKS 



EXECUTIVE 



PHYSICAL MEMORY 
TIME 1 



PHYSICAL MEMORY 
TIME 2 



Figure 5-1 Typical Resident Common 



When you build a shared region, you m 
name for the region in the TKB 
shared region is not an executable un 
not require a header or a stack a 
shared region, you always attach the 
the region's image file specif ica 
suppress the header within the image, 
the Task Builder command sequence 
STACK=0. (Refer to Chapters 10 and 1 
the /HD switch, the STACK option, and 



ust specify an output image file 
command sequence. But, because a 
it, it is not a task, and does 
rea. Therefore, when you build a 
negated header switch (/-HD) to 
tion. This switch tells TKB to 
To suppress the stack area in 

during option input, you specify 
1 for a complete description of 

other switches and options.) 



In either an RSX-llM or RSX-llM-PLUS system, when you build a shared 
region, you use the PAR option to name the partition in which the 
region is to reside. You specify the partition name in the TKB 
command sequence durin*^ option in^ut. ^Refer to Chs^ter 11 for a 
description of the PAR option.) In an RSX-llM system, the partition 
named in the PAR option must previously exist when the common is 
installed. It need not exist when the common is being built by TKB. 
In an RSX-liM-^pnus system, the partition named in the PAR option need 
not previously exist, but the actual partition defaults to- GEN, On 
both systems, the name used in the PAR option must be the same name as 
that of the region. 

In an RSX-llM system, a shared region must reside in Its own 
partition. Therefore, when you generate your system, you must 
consider the physical memory requirements, in terms of partitions, for 
any shared regions that you expect to reside within your system. If 

later, when you build a shared region, you will be forced to go back 
and create a common partition for the region. 
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Figure 5-2 Typical Resident Library 
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5.1.1 The Symbol Definition File 

When you build a shared region, you must specify a symbol definition 
(.STB) file in the TKB command sequence. This file contains linkage 
information about the region. (The format at a .STB file as input to 
TKB is the same as that of a .OBJ file. See Appendix A.) Later, when 
you build a task that links to the region, TKB uses this .STB file to 
resolve calls from within the referencing task to locations within the 
region. 



The /PI switch declares a shared region to 
Conversely, the /-PI switch declares a shared regi 
If you specify the /PI switch without the /CO or 
indicate a relocatable region, TKB defaults to bu 
(position-independent) shared regions with all 
declared in the .STB file. TKB also defaults to 
(position-dependent) shared regions with only the 
section declared in the .STB file. The contents of 
these three switches are used are described in Chapt 
/CO, /LI, and /PI switch headings. See also Figur 
of the /LI, /CO, and /PI Switches. 
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Figure 5-3 Interaction of the /LI, /CO, and /PI Switches 
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If you do not use either /CO or /LI, the contents of an .STB file for 
a shared region depend on the use of the /PI switch, which determines 
whether the region is absolute or relocatable. The effects of 
declaring a shared region relocatable or absolute and the resulting 
contents of the .STB file are described in the following sections. 

Some .STB files include an entry in the .STB file for each program 
section in the region. Each entry declares the program section's 
name, attributes, and length. In addition, TKB includes in the .STB 
file every symbol in the shared region and its value relative to the 
beginning of the section in which it resides. 



5.1.2 Position-Independent Shared Regions 

A position-independent shared region can be placed anywhere in a 
referencing task's virtual address space when the system on which the 
task runs has memory management hardware. 



5.1.2.1 Position-Independent Shared Region Mapping - In the example 
of using the memory management APRs, shown in Figure 5-4, two tasks 
refer to the shared region S: task A and task B. The shared region S 
is 4K words long and therefore requires that much space in the virtual 
address space of both tasks. Task A is 6K words long and requires two 
APRS (APRO and APRl) to map its task region. The first APR available 
to map the shared region is APR 2. Thus, you can specify APR 2 when 
task A is built. 

Task B is 16. 5K words long. It requires five APRs to map its task 
region. The first APR available to map the shared region S in task B 
is APR 5. Therefore, you can specify APR 5 when task B is built. 

If you do not specify which APR is to be used to map a 
position-independent shared region, TKB selects the highest set of 
APRS available in the referencing task's virtual address space. In 
Figure 5-4, for example, if APR 2 in task A and APR 5 in task B had 
not been selected at task-build time, TKB would have selected APR 7 in 
both cases . 



5.1.2.2 Specifying a Position-Independent Region - You specify that a 
shared region is position independent when you build it by attaching 
the /PI switch to the image file specification for the region. (Refer 
to Chapter 10 for a description of the /PI switch.) 

You should declare a region position independent if: 

• The region contains code that will execute correctly 
regardless of its location in the address space of the 
referencing task. 

• The region contains data that is not address dependent. 

• The region contains data that will be referenced by a FORTRAN 
program (such data must reside in a named common) . 
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Figure 5-4 Specifying APRs for a Position-Independent Shared Region 
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Program section names are preserved in some shared regions. All the 
following switch combinations produce shared regions in which PSECT 
names are preserved: 

/PI/CO, /-PI/CO, and /PI 

Therefore, you should observe the following precautions when building 
and referring to these regions: 

• No code or data in the region should be included in the blank 
(. BLK.) program section, 

• No code or data in a referencing task should appear in a 
program section of the same name as a program section in the 
shared region. 

• The order in which memory is allocated to program sections 
(alphabetic or sequential) must be the same for the shared 
region and its referencing tasks. (Chapter 2 describes 
alphabetic ordering of program sections. Refer to the 
description of the /SQ and /SG switches in Chapter 10 for an 
explanation of sequential ordering of program sections.) 



5.1.3 Absolute Shared Regions 

When a shared region is absolute, you select the virtual addresses for 
it when you build it. Thus, an absolute shared region is fixed in the 
virtual address space of all tasks that refer to it. 



5.1.3.1 Absolute Shared Region Mapping - Figure 5-5 shows three tasks 
(task C, task D, and task E) and a single absolute shared region, L. 
The absolute shared region L is 6K words long and is built to occupy 
virtual addresses 120000 (octal) to 150000 (octal) . These addresses 
correspond to APR 5 and APR 6, respectively. Tasks C and D can be 
linked to region L because at the time they are built APR 5 and APR 6 
are unused in both tasks. However, task E is 23K words long and even 
though it has 8K words of virtual address space available to map the 
shared region, APR 5 (which corresponds to virtual address 120000, the 
base address of the shared region) has been allocated to the task 
region. If shared region L were position independent, task E could be 
linked to it. 



5.1.3.2 Specifying an Absolute Shared Region - You specify that a 
shared region is absolute when you build it by using the /-PI switch 
or omitting the /PI switch from the task image file. You establish 
the virtual address for the region by specifying the base address of 
the region as a parameter of the PAR option. 

You should build an absolute shared region if: 

• The region contains code that must appear in a specific 
location in the address space of a referencing task. 

• The region contains data that is address dependent. 

w xiie region conuains program secuions Oi 
program sections in referencing tasks. 
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Figure 5-5 Mapping for an Absolute Shared Region 



5-8 



SHARED REGION CONCEPTS AND EXAMPLES 

5.1.3.3 Absolute Shared Region .STB File - When a shared region is 
created with the /-PI/LI or /-PI switches, or just the /-HD switch, 
the only program section name that appears in the .STB file for the 
region is the absolute program section name (. ABS.). TKB includes in 
the .STB file for the region each symbol in the region and its value. 
But, because TKB does not include the program section names of an 
absolute shared region in its .STB file, all code or data in the 
region must be referred to by global symbol name. Also, because the 
program section names are not in the .STB file, TKB places no 
restrictions on the way the program sections are ordered in either the 
absolute shared region or the tasks that reference it. You can order 
program sections the way you want by using the /SQ and /SG switches 
described in Chapter 10. 



5.1.4 Shared Regions with Memory- Resident Overlays 

Shared regions with memory-resident overlays are a primary resource 
for conserving memory. If the shared region is larger than the 
available virtual address space in a task that must reference the 
region, you can build the region — both position-independent and 
absolute — with memory-resident overlays. All segments of the 
overlay structure are included in the shared region, but each task 
referencing the shared region can include only part of the shared 
region — that is, an overlay segment or series of segments in an 
overlay path — in its virtual address space. Therefore, the task 
need only have enough virtual address space for the largest shared 
region overlay segment, or series of segments in an overlay path, it 
is likely to access. Hence, the virtual address space of the task can 
be considerably smaller than the size of the shared region. 



5.1.4.1 Considerations About Building an Overlaid Shared Region - In 
general, overlays can be disk-resident or memory-resident, but those 
in shared regions must, by their very nature, be memory-resident. TKB 
marks each overlay segment in the shared region with the NODSK 
attribute to suppress overlay load requests. When you build a shared 
region with memory-resident overlays, you must define the overlay 
structure through a conventional DDL file. (See Chapters 3 and 4 of 
this manual for information on overlays and the Overlay Description 
Language.) TKB does not include the overlay data base (segment 
descriptors, autoload vectors, and so forth) or the overlay run-time 
routines within the region image. Instead, this data base becomes a 
part of the .STB file that is linked to the referencing task. When 
this task is built, its root segment automatically includes both the 
data base and global references to overlay support routines residing 
in the system object module library. 

The procedure for creating a shared region with memory-resident 
overlays can be summarized as follows: 

• Define an overlay structure containing only memory-resident 
overlays . 

• Include the GLBREF option, or provide in the root segment a 
module containing the appropriate global references for 
defining entry points within those overlay segments ,= TKB 
generates autoload vectors and global definitions for the 
overlay segments. 
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5.1.4.2 Example of Building a Memory- Resident Overlaid Shared Region 

- The procedure for creating a shared region is illustrated in the 
following example. The shared region to be contructed consists of 
reentrant code that resides within the overlay structure defined 
below: 

.ROOT A-! (B,C-D) 

.NAME A 

.END 

Root segment A contains no code or data and has a length of 0. All 
executable code exists within memory-resident overlay segments 
composed of object modules B.OBJ, C.OBJ, and D.OBJ, containing global 
entry points B, C, and D, respectively. 

You generate the .TSK, .MAP, and .STB files by using the following TKB 
commands : 

TKB> A/-HD/MM , LP : , SY : A=A/MP 
Enter Options: 
TKB>GBLREF=B ,C , D 
TKB>PAR=A: 16000 0:2000 
TKB>STACK=0 
TKB>/ 



NOTE 

When building a shared region, you must 
use the same name for the partition and 
the .TSK and .STB files. 

See the PAR, RESLIB, LIBR, RESCOM, and 
COMMON options in Chapter 11. 

TKB inserts references to entry points B, C, and D in the root segment 
of the library which subsequently appear in the .STB file as 
definitions . 

TKB resolves the definitions for symbol C directly to the actual entry 
point. TKB resolves the definitions for symbols B and D to autoload 
vectors that it includes in each referencing task. 



5.1.4.3 Options for Use in Overlaid Shared Regions - Certain options 
may prove useful to you when building and linking shared regions to a 
task. They are described next. 

GBLDEF — You can declare the definition of a symbol by means of the 
GBLDEF option. The syntax of this option is: 

GBLDEF= symbol-name:symbol-value 

where symbol-name is a 1- to 6- character Radix-50 name of the defined 
symbol and symbol-value is an octal number in the range of through 
177777 assigned to the symbol. This option is frequently used in the 
TKB build file for a task or shared region to allow you to alter the 
value of a global symbol that resides in a module. This saves you the 
trouble of reassembling the source code for a module if changes are 
necessary. 
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GBLINC — By means of this option, you force TKB to include the 
specified symbols in the .STB file being created by the linking 
process in which this option appears. The syntax of this option is: 

GBLINC=symbol-name, symbol-name , . . . , symbol-name 

where symbol-name is the symbol or symbols to be included. Use this 
option when you want to force particular modules to be linked to the 
task that references this library. The global symbol references 
specified by this option must be satisfied by some module or GBLDEF 
specification when you build the task. 

GLBREF — You can force the inclusion of a global reference in the 
root segment of the shared region by means of the GBLREF option. In 
this way, the necessary autoload vectors and definitions can be 
generated without explicitly including such references in an object 
module. The syntax of the option is: 

GBLREF= [ , name [ , name . . . ] ] 

where the name consists of from one to six Radix-50 characters. If 
the definition resides within an autoloadable segment, TKB constructs 
an autoload vector and includes it in the symbol definition file. If 
the definition is not autoloadable, TKB obtains the real value and 
defines it in the root segment. No global symbol appears in the .STB 
file unless the symbol is either defined in the root segment or is 
referenced in the root segment and defined elsewhere in the overlay 
structure. 

GBLXCL — You can exclude a symbol or symbols from the symbol 
definition file of a shared region by means of the GBLXCL option. The 
syntax of this option is: 

GBLXCL=symbol-name, symbol-name , . . . , symbol-name 

where symbol-name is the symbol or symbols to be excluded. You can 
use this option when you do not want the task to be aware of specific 
symbols within the library. This option is particularly useful when 
you cluster overlaid libraries together (see the CLSTR option in 
Chapter 11 and the Cluster Libraries section in this chapter) . 



5.1.4.4 Autoload Vectors and .STB Files for Overlaid Shared Regions - 

When TKB builds a task image file containing memory-resident overlays, 
TKB allocates autoload vectors in the task image. If the task links 
to a shared region, autoload vectors for the shared region are also 
allocated in the task image. TKB allocates the autoload vectors in 
the task's root segment, but not in the shared region. Therefore, the 
shared region cannot reference unloaded (unmapped) segments of its 
overlay structure. 

When the task executes, the shared region is effectively part of the 
task. In fact, when the task loads overlay segments, it makes no 
distinction between overlay segments of the task and those of the 
shared region. They are loaded as needed in a procedure that is 
transparent insofar as the execution of the task is concerned. 

For the Fast Task Builder (FTB) and older versions of TKB that do not 
support overlaid I- and D-space tasks, each autoload vector in the 
shared region's .STB file is allocated in the root of the task being 
linked to the region, whether or not the entry point is referenced by 
the task. 
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However, if you use a version of TKB that supports overlaid I- and 
D-space tasks and the library was built with one of these versions, 
TKB allocates autoload vectors in the root of the task only for those 
autoloadable entry points in the library that the task references. 
The .STB file contains ISD records that allow TKB to create 
dynamically autoload vectors when linking the task to the lit»rary.. 
TKB ignores the autoload vectors in the .STB file if the ISD records 
are present. Therefore, tasks that link to overlaid shared regions 
and that are built with newer versions of TKB tend to be smaller and 
use less virtual address space than those that are built by FTB or 
older versions of TKB. 



NOTE 

Libraries created with older versions of 
TKB do not have the ISD records in the 
.STB file that newer versions of TKB use 
to include autoload vectors in the task 
from the .STB file. Therefore, TKB must 
create autoload vectors for every entry 
point in the library. 

If you are using one of these older 
libraries and you are linking an I- and 
D-space task to it, TKB will give you 
the fatal error message: 

"Module module-name contains 
incompatible autoload vectors." 

This message occurs because the .STB 
file contains conventional autoload 
vectors that are not usable by an I- and 
D-space task. 

Only those global symbols defined or referenced in the root segment of 
the shared region appear in the .STB file. The .STB file also 
contains the data base required by the overlay run-time system in 
relocatable object module format. This data base includes: 

• All autoload vectors 

• Segment tables (linked as described in Appendix B) 

• Window descriptors 

• A single region descriptor 

The overlay structure, as reflected in the segment table linkage, is 
preserved and conveyed to the referencing task by the ,STB file. 
Thus, path loading for the shared region can occur exactly as it does 
within a task. Aside from address space restrictions, there are no 
limitations on the overlay structures that can be defined for a shared 
region. 
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5.1.5 Run-Time Support for Overlaid Shared Regions 

Memory-resident overlays within a shared region require little 
additional support from the overlay run-time system. The shared 
region overlay data base that is linked within the image of the 
referencing task has a structure that is identical to the equivalent 
data created for an overlaid task. Therefore, memory-resident 
overlays within the shared region are indistinguishable from 
memory-resident overlays that form a part of the task image. The only 
additional processing is that required to attach the shared region and 
obtain its identification for use by the mapping directives. 

Once this initialization is complete, all further processing is 
identical to memory-resident overlay processing performed on task 
overlays. 

Several restrictions apply to shared regions existing as 
memory-resident overlays: 

• A shared region cannot use the autoload facility to reference 
memory-resident overlays within itself or any other region. 
If each segment is uniquely named, overlays can be mapped 
through the manual load facility. 

• Named program sections in a shared region overlay segment 
cannot be referenced by the task. If reference to the storage 
is required, such sections must be included in the root 
segment of the region (with resultant loss of virtual address 
space) . 

• For FTB, and libraries built with versions of TKB that do not 
support I- and D-space overlaid tasks, the number of autoload 
vectors is independent of the entry points actually 
referenced. The maximum number of vectors will be allocated 
within each referencing task. In some cases the size of the 
allocation will be large. 

• There is an overhead of six instructions per autoload call, 
even when the segm^.-nb is mapped. The overhead is seven 
instructions for an overlaid I- and D- space task. 

As implied by the previous items, great care must be exercised if an 
efficient memory-resident overlay structure for library routines such 
as the FORTRAN IV OTS is to be implemented. 



5.1.6 Linking to a Shared Region 

When you build a task that links to a shared region, you must indicate 
to TKB the name of the shared region and the type of access the task 
requires to it (read/write or read-only) . In addition, if the shared 
region is position independent, you can specify which APR TKB is to 
allocate for mapping the region into the task's virtual address space. 
Four options are available for this action: 

• RESLIB (resident library) 
9 RSSCOM (resiuent common) 

• LIBR (system-owned resident library) 

• COMMON (system-owned resident common) 
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RESLIB and RESCOM accept a complete file specification as one of their 
arguments. Thus, you can specify a device and UFD indicating to TKB 
the location of the region's image file and, by implication, its 
symbol definition file. (Refer to Chapter 1 for more information on 
file specifications and defaults.) 

LIBR and COMMON accept a 1- to 6-character name. When you specify 
either of these options, the shared region's image file and symbol 
definition file must reside under UFD [1,1] on device LBO:. 

The RESLIB and RESCOM options require that all users of the shared 
region know the UFD under which the shared region's image file and 
•STB file reside. The LIBR and COMMON options require only that the 
users of the shared region know the name of the shared region. When 
you specify either LIBR or COMMON, by default, TKB expects to find the 
shared region's image and .STB files on device LB: under UFD [1,1]. 

All four options accept two additional arguments: 

• The type of access that the task requires (RO or RW) . 

• The first APR that TKB is to allocate for mapping the region 
into the task's virtual address space. As stated earlier, 
this argument is valid only when the shared region is position 
independent. 

When you specify any of these options, TKB expects to find a symbol 
definition file of the same name as that of the shared region, but 
with an extension of .STB, on the same device and under the same UFD 
as those of the shared region's image file. 

The syntax of these options is given in Chapter 11. 

When TKB builds a task, it processes first any options that appear in 
the TKB command sequence. When TKB processes one of the four options 
above, it locates the disk image of the shared region named in the 
option. The disk image of a shared region does not have a header, but 
it does have a label block that contains the allocation information 
about the shared region (for example, its base address, load size, and 
the name of the partition for which it was built) . TKB extracts this 
data from the shared region's label block and places it in the LIBRARY 
REQUEST section of the label block for the referencing task. 

The .STB file associated with the shared region is an object module 
file. TKB processes it as an input file. If the shared region is 
position independent, its .STB file contains program section names, 
attributes, and lengths. However, the program section names are 
flagged within the file as "library" program sections and TKB does not 
add their allocations to the task image it is building. 

If the task links to only one shared region, and if neither the shared 
region nor the task that links to it contain memory-resident overlays, 
the Task Builder allocates two window blocks in the header of the 
task. (Overlays are described in Chapter 3.) When the task is 
installed, the INSTALL processor will initialize these window blocks 
as follows: 

• Window block will describe the range of virtual addresses 
(the window) for the task region. 

• Window block 1 will describe the window for the shared region. 
Figure 5-6 shows the window-to-region relationship of such a task. 



5-14 



SHARED REGION CONCEPTS AND EXAMPLES 



HIGHEST VIRTUAL 
ADDRESS 



WINDOW BLOCK 
1 




WINDOW BLOCK 




WINDOW 




LOWEST VIRTUAL 
ADDRESS 



SHARED 
REGION 



UNuSbD 



TASK 
MEMORY 



HEADER AND STACK 



Figure 5-6 Windows for Shared Region and Referencing Task 
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A shared region need not be installed before a task that links to it 
is built. The .STB file that you specify when you build the shared 
region contains all the information required by TKB to resolve 
references from within a task to locations within the shared region. 
The only requirement is that you install a shared region before you 
install a task that links to it. 

Unless you use the /LI switch, there is a restriction on the way TKB 
processes tasks that link to relocatable shared regions. TKB places 
all program section names into its internal control section table. 
The program section names include those from the .STB file of the 
shared region as well as those from the other input modules, A 
conflict can arise when building a task that contains program sections 
of the same name as those in the shared region to which the task 
links. The conflict arises because TKB tries to add the program 
section allocation in the task to the already existing allocation for 
the program section of the same name in the region. This is not 
possible because the region's image has already been built, is outside 
the address space of the task currently being built, and cannot be 
modified. Therefore, to avoid this conflict, the program section 
names within a task that links to a relocatable shared region must 
normally be unique with respect to program section names within the 
shared region. 

TKB displays an error message under the following conditions: 

• A program section in the task and a program section in the 
shared region have the same name. 

• The program section in the task contains data. 

• TKB tries to initialize the program section in the task. 

The error message occurs when TKB tries to store data in an image 
outside the address limits of the task it is building. If this 
conflict occurs, TKB prints the following message: 

TKB — *DIAG*-load addr out of range in module module-name 

One exception to the above restriction develops when all of the 
following conditions exist: 

• Both program sections (in the shared region and in the 
referencing task) have the (D) data and the OVR (overlay) 
attributes. 

• The program section in the task is equal to or shorter than 
the program section in the shared region. 

• The program section in the task does not contain data. 

When all of these conditions exist, there is nothing to be initialized 
within the shared region. TKB binds the base address of the program 
section in the task to the base address of the program section in the 
shared region. If the program section in the task contains global 
symbols, TKB assigns addresses to them that reflect their location 
relative to the beginning of the program section. You can use this 
technique to establish symbolic offsets into resident commons. 
Examples 5-1 and 5-2 in the following sections illustrate how to 
establish these offsets. 
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5.1.7 Number and Size of Shared Regions 

The number of shared regions to which a task can link is a function of 
the number of window blocks required to map the task and the regions. 
In an RSX-llM 'operating system, if a "task is "4K -words, or less," and 
each shared region to which the task links is 4K words. or less, then a, 
nonprivileged task can access as .many as/ seven shared regions. 

In an RSX-llM-PLOS operating system, if a task is 4K words or less, 
and each shared region to- which the task links is 4K words or less, a 
nonpriyileged task can. refer to .as many as, 15 shared regions-:.,: 7 in 
user mode 'and 3 in supervisor mode,.; (Supervisor-mode libraries are- 
•described, in Chapter 8..).: - , ' . :- ; ■- 



5.1.8 Example 5-1: Building and Linking to a Common in MACRO-11 

The text in this section and the figures associated with it illustrate 
the development of a MACRO-11 position-independent resident common and 
the development of two MACRO-11 tasks that share the common. The 
steps in building a position-independent common can be summarized as 
follows: 

1. You create a source file that allocates the amount of space 
required for the common. In MACRO-11, either of the 
assembler directives, .BLKB or .BLKW, provide the means of 
allocating this space. 

2. You assemble the source file. 



3. You build the assembled module, specifying both a task 
file and a symbol definition file. 



image 



You specify the /-HD (no header) switch and declare the 
common with /CO. You specify the common to be position 
independent with the /PI switch. 

Under options you specify: 

STACK=0 
PAR=parname 

The parname in this PAR option is the name of the partition 
in which the common is to reside. (The /HD and /PI switches 
and the STACK and PAR options are described in Chapter 10.) 

If your system is an RSX-llM system, the common must reside 
within a common partition of the same name as that of the 
common. 



If your system is an RSX-llM-PLOS system, the common 
reside within any partition large enough to hold it. 



can 



4. You install the common. 

Example 5-1 below shows a MACRO-11 source file that, when assembled 
and built, creates a position-independent resident common area named 
MACCOM. The common area consists of two program sections named COMl 
and COM2, respectively. Each program section is 512(decimal) words 
long . 
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Example 5-1, Part 1 Common Area Source File in MAGRO-11 

.TITLE MACCOM 

COMl - 512 WORDS 
COM2 - 512 WORDS 

.PSECT C0M1,RW,D,GBL,REL,0VR 
.BLKW 512. 

.PSECT C0M2,RW,D,GBL,REL,0VR 
.BLKW 512. 

.END 

Once this common has been assembled, the Task Builder command sequence 
shown below can be used to build it. 

>TKB 

TKB>MACCOM/P I /- HD/CO , MACCOM/- S P , MACC0M=MACC0M 

TKB>/ 

Enter Options: 

TKB>STACK=0 

TKB>PAR=MACCOM: : 4000 

TKB>// 

This command sequence directs TKB to build a position-independent 
(/PI) , headerless (/-HD) common image file named MACCOM. TSK. It also 
specifies that the Task Builder is to create a map file, MACCOM. MAP, 
and a symbol definition file, MACCOM. STB. TKB creates all three 
files — MACCOM. TSK, MACCOM. MAP, and MACCOM. STB — on device SY: 
under the UFD that corresponds to the terminal UIC. Because /-SP is 
attached to the map file, TKB will not spool a map listing to the line 
printer. 

Under options, STACK=0 suppresses the stack area in the common's 
image. The PAR option specifies that the common area will reside 
within a common partition of the same name as that of the common, 
MACCOM. In addition, the parameters in the PAR option specify a base 
of and a length of 4000 octal bytes for the common. (Refer to 
Chapters 10 and 11 for descriptions of the switches and options used 
in this example.) 

Example 5-1, Part 2 shows the map resulting from this command 
sequence. 

The task attributes section of this map reflects the switches and 
options of the command string. It indicates that the common resides 
in a partition named MACCOM, that it was built under terminal UIC 
[7,62], that it is headerless and position independent, and that it 
requires one window block to map. The total length of the common is 
1024 (decimal) words and its address limits range from to 
3777 (octal). The common image (that portion of the disk image file 
that eventually will be read into memory) begins at file-relative disk 
block 2 O • The last block in the file is file-relative disk block 
5 @ and the common image is four blocks long Q . 

The memory allocation synopsis details the Task Builder's allocation 
for and the attributes of the program sections within the common. For 
example, reading from left to right, the map indicates that the 
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program section COMl permits read/write access, that it contains data, 
and that its scope is global. It also indicates that COMl is 
relocatable and that all contributions to COMl are to be overlaid. 
Because COMl has the overlay attribute, the total allocation for it 
will be equal to the largest allocation request from the modules that 
contribute to it. (For more information on program section 
attributes, see Chapter 2.) 

Continuing to the right, the first 6-digit number is COMl's base 
address, which is ©. The next two digits are its length (bytes) in 
octal and decimal, respectively. 

The next line down lists the first object module that contributes to 
COMl. In this case there is only one: the module MACCOM from the 
file MACCOM. 0BJ;1. The numbers on this line indicate the relative 
base address of the contribution and the length of the contribution in 
octal and decimal @ . If there had been more than one module input to 
TKB that contained a program section named COMl, TKB would have listed 
each module and its contribution in this section. 

Notice that there is a program section named . ELK. shown on the map 
just above the field for COMl. This is the "blank" program section 
that is created automatically by the language translators. The 
attributes shown are the default attributes. The allocation for 
. BLK. is because the program sections in MACCOM were explicitly 
declared. If the program sections had not been explicitly declared, 
all of the allocation for the common would have been within this 
program section. 



Example 5-1, Part 2 Task Builder Map for MACCOM. TSK 



MACCOM. TSK;1 Memory allocation map TKB M40.10 

17-NOV-82 16:05 



Page 1 



Partition name : MACCOM 

Identification : 

Task UIC : [7,62] 

Task attributes: -HD,PI 

Total address windows: 1. 

Task image size : 1024. WORDS 

Task address limits: 000000 003777 

R-W disk blk limits: 000002 000005 000004 00004. 



~\: 



*** Root segment: MACCOM' 






"T" 



R/W mem limits: 000000 003777 004000 02048. 
Disk blk limits: 000002 000005 000004 00004. 



Memory allocation synopsis: 
Section 



. BLK. : (RW,I,LCL,REL,CON) 000000 000000 00000. 
COMl : (RW,D,GBL,REL,OVR) 000000 002000 01024 , 



000000 
COM2 : (RW,D,GBL,REL,OVR) 002000 

002000 



/ 

O 



002000 
002000 
002000 



01024, 
01024. 



Title 

.MAIN. 
.MAIN. 



Ident File 



MACCOM. OB J; 1 
MACCOM. OBJ; 1 



(continued on next page) 
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Example 5-1, Part 2 (Cont.) Task Builder Map for MACCOM.TSK 



*** Task builder statistics: 

Total work file references: 183. 

Work file reads: 0. 

Work file writes: 0. 

Size of core pool: 7086. WORDS (27. PAGES) 

Size of work file: 768. WORDS (3. PAGES) 

Elapsed time : 00 :00 : 05 



Figure 5-7 is a diagram that represents the disk image file for 
MACCOM. The circled numbers in Figure 5-7 correspond to the circled 
numbers in Example 5-1, Part 2. 



RELATIVE 
DISK BLOCK 
NUMBERS 



RELATIVE 

LOAD 

ADDRESSES 



000005 




000004 — 



000003 — 



000002 — 



^ 



000001 — 



000000 — 



COM 2 



COM 1 



LABEL BLOCK 



_ 002000 



^ 



000000 - 



- 002000 (BYTES) 



^ 



DISK IMAGE FILE 
Figure 5-7 Allocation Diagram for MACCOM.TSK 



Once you have built MACCOM, you can install it. If your system is an 
RSX-rllM system, the coiiunon i^ loaded into memory when you install it. 

If your system is an RSX-llM-PLUS system, it remains there until you 
explicitly remove it with the MCR command REMOVE. The common will not 
be loaded until either one of the following occurs: 

• A task that is linked to it is run. 

• You explicitly fix the common in memory with the MCR command 

FIX. 
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Example 5-1, Parts 3 and 4 show two programs: MCOMl and MC0M2 , 
respectively. Both of these programs reference the common area MACCOM 
created above. MCOMl in Example 5-1, Part 3 accesses the COMl portion 
of MACCOM. It inserts into the first 10 words of COMl the numbers 1 
through 10 in ascending order. It then issues an Executive directive 
request for the task MC0M2 and suspends itself. 

When MC0M2 runs, it adds together the integers left in COMl by MCOMl 
and leaves the sum in the first word of COM2, It then issues a resume 
directive for MCOMl and exits. 

When MCOMl resumes, it retrieves the answer left in COM2 and calls the 
system library routine $EDMSG (edit message) to format the answer for 
output to device TI : . 

All of the Executive directives for both programs (RQST$C, SPND$S, 
QIOW$S, RSUM$C, and EXIT$S) are documented in the RSX-llM-PLUS 
Executive Reference Manual . The system library routine $EDMSG is 
documented in the IAS/RSX-11 System Library Routines Reference Manual . 

Example 5-1, Part 3 MACRO-11 Source Listing for MCOMl 



.TITLE MCOMl 
. IDENT /Ol/ 



.MCALL EXIT$S,SPND$S,RQST$C,QIOW$S 



OUT: 

FORMAT: 

MES: 



.BLKW 
.ASCIZ 
.ASCII 
LEN = . 
.EVEN 



100. 

/THE RESULT IS %D./ 
/ERROR FROM REQUEST/ 
- MES 



; SCRATCH AREA 



; PSECT - COMl IS USED TO ACCESS THE FIRST 512. WORDS OF THE 
; COMMON. 

.PSECT C0M1,GBL,0VR,D 
INT: .BLKW 10. 

; PSECT - COM2 IS USED TO ACCESS THE SECOND 512. WORDS OF THE 
; COMMON. IT WILL CONTAIN THE RESULT 



ANS: 



.PSECT 
.BLKW 



COM2, GEL, OVR,D 

1 



START: 



.PSECT 

MOV 
MOV 
MOV 



#10.,RO 

#1,R1 

#INT,R3 



NUMBER OF INTEGERS TO SUM 
START WITH A 1 

PLACE VALUES IN 1ST 10 WORDS 
OF COMMON 



(continued on next page) 
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Example 5-1, Part 3 (Cont.) MACRO-11 Source Listing for MCOMl 



10$: 



ERRl: 



MOV 


Rl, (R3)+ 


INC 


Rl 


DEC 


RO 


BNE 


10$ 


RQST$C 


MC0M2 


BCS 


ERRl 


SPND$S 




MOV 


#OUT,R0 


MOV 


# FORMAT, Rl 


MOV 


#ANS,R2 


CALL 


$EDMSG 


QIOW$S 


#I0.WVB,#5 


EXIT$S 




QIOW$S 


#I0.WVB,#5 


EXIT$S 




.END 


START 



INITIALIZE COMMON 

NEXT INTEGER 

ONE LESS TIME 

TO INITIALIZE 

REQUEST THE SECOND TASK 

REQUEST FAILED 

WAIT FOR MC0M2 TO SUM THE INTEGERS 

ADDRESS OF SCRATCH AREA 

FORMAT SPECIFICATION 

ARGUMENT TO CONVERT 

DO CONVERSION 



Example 5-1, Part 4 MACRO-11 Source Listing for MC0M2 



.TITLE MC0M2 

.IDENT /Ol/ 

.MCALL EXIT$S,QIOW$S,RSUM$C 

MES: .ASCII /ERROR FROM RESUME/ 

LEN = . - MES 
.EVEN 

; PSECT - COMl IS USED TO ACCESS THE FIRST 10. WORDS OF THE 
: COMMON. 



INT: 



.PSECT C0M1,GBL,0VR,D 
.BLKW 10. 



ANS; 



START: 



10$: 



ERR: 



PSECT - COM2 IS USED TO ACCESS THE SECOND 10. WORDS OF THE 
COMMON. IT WILL CONTAIN THE RESULT 



.PSECT 
.BLKW 


C0M2,GBL,0VR,D 

1 


.PSECT 




MOV 
MOV 


#10. ,R0 
#INT,R3 


CLR 


ANS 


ADD 
DEC 
BNE 


(R3)+,ANS 

RO 

10$ 


RSUM$C 

BCS 

EXIT$S 


MCOMl 
ERR 



NUMBER OF INTEGERS TO SUM 

PLACE VALUES IN 1ST 10 WORDS 

OF COMMMON 

INITIALIZE ANSWER 

ADD IN VALUES 

ONE LESS VALUE 

TO SUM 

; RESUME MCOMl 
; RESUME FAILED 



QIOW$S #IO.WVB,#5,#1,,,,<#MES,#LEN,#40> 

EXIT$S 

.END START 
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Note that both tasks MCOMl and MC0M2 contain .PSECT declarations 
establishing program section names that are the same as program 
section names within the position-independent common to which the task 
is linked (MACCOM) . As stated earlier, in most circumstances this 
would be illegal. In this application, however, the .PSECT directives 
have been placed into the tasks to establish symbolic offsets in the 
resident common. When either task is built, TKB assigns to the symbol 
INT: the base address of program section COMl, and to the symbol ANS : 
the base address of program section COM2. Figure 5-8 illustrates this 
assignment . 



ANS: 



ANS: 



INT:. 



INT:-^ 



COM 2 



COM 1 



Figure 5-8 Assigning Symbolic References within a Common 

Once you have assembled MCOMl and MC0M2, you can build them with the 
following TKB command sequences: 

>TKB 

TKB>MC0M1 ,MC0M1/-SP=MC0M1 

TKB>/ 

Enter Options: 

TKB>RESCOM=MACCOM/RW 

TKB>// 



>TKB 

TKB>MC0M2 ,MCOM2/-SP=MCOM2 

TKB»/ 

Enter Options: 

TKB> RESCOM=MACCOM/RW 

TKB>// 



Under options in both of these command sequences, the RESCOM option 
tells TKB that these programs intend to reference a common data area 
named MACCOM and that the tasks require read/write access to it. 
Because the RESCOM option is used, TKB expects to find the image file 
and the symbol definition file for the common on device SY: under the 
UFD that corresponds to the terminal UIC, In addition, because the 
optional APR specification was omitted from the RESCOM option, TKB 
allocates virtual address space for the common starting with APR7 in 
both tasks (the highest APR available in both tasks) . 
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The TKB map for MCOMl is shown in Example 5-1, Part 5. The map for 
MC0M2 is not essentially different from that of MCOMl and is therefore 
not included here. 



Example 5-1, Part 5 Task Builder Map for MCOMl. TSK 



MCOMl. TSK;1 Memory allocation map TKB M40.10 Page 1 

ll-DEC-82 16:12 



Partition name : GEN 

Identification : 01 

Task UIC : [7,62] 

Stack limits: 000274 001273 001000 00512. 

PRG xfr address: 001650 

Total address windows: 2. 

Task image size : 1184. WORDS 

Task address limits: 000000 004407 

R-W disk blk limits: 000002 000006 000005 00005. 

*** Root segment: MCOMl 



R/W mem limits: 000000 004407 004410 02312. 
Disk blk limits: 000002 000006 000005 00005. 



Memory allocation synopsis: 
Section 



Title Ident File 



BLK. : (RW,I,LCL,REL,CON) 



COMl 



(RW,D,GBL,REL,OVR) 



COM2 : (RW,D,GBL,REL,OVR) 
$DPB$$: (RW, I,LCL,REL,CON) 



$$RESL: (RO,I,LCL,REL,CON) 004176 000212 00138. 



001274 


002664 


01460. 










001274 


000574 


00380. 


MCOM 


01 


MCOMl, 


.0BJ;1 


160000 


002000 


01024. 










160000 


000024 


00020. 


MCOM 


01 


MCOMl, 


.0BJ;1 


162000 


002000 


01024. 










162000 


000002 


00002. 


MCOM 


01 


MCOMl, 


.0BJ;1 


004160 


000016 


00014. 










004160 


000016 


00014. 


MCOM 


01 


MCOMl. 


,0BJ;1 



*** Task builder statistics: 



Total work file references: 1924, 
Work file reads: 0. 
Work file writes: 0. 
Size of core pool: 7086. 
Size of work file: 1024, 



WORDS (27. PAGES) 
WORDS (4. PAGES) 



Elapsed time : 00 : 00 : 04 
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Note that TKB has placed two window blocks in MCOMl ' s header. When 
MCOMl is installed, the INSTALL processor will initialize these window 
blocks as follows: 

• Window block will describe the range of virtual addresses 

(the window) for MCOMl ' s task region. 

• Window block 1 will describe the window for the shared region 
MACCOM. 



5.1.9 Linking Shared Regions Together 

Shared regions can link to other shared regions. You may find it 
convenient to have code in a shared library and have access to 
routines in another shared library to which it links. 

The following text describes, as an example for a mapped system, the 
TKB command sequence for building a resident library named FILES. 
That text is followed by a TKB command sequence that shows an example 
of building another resident library named FORCOM that links to FILEB. 
Following after that, a TKB command sequence shows the building of a 
task that links to FORCOM. In the TKB command sequences to follow, it 
is assumed that you know the contents of the libraries and the task. 
The examples show the linkage only. 

The first shared region to be built is called FILEB. The library 
FILEB is a position-dependent library. You use the /-PI switch to 
signify that the library is absolute. You build the library with the 
/-HD switch to indicate that the library has no header. The /LI 
switch indicates that FILEB is to be a shared library. The program 
section name of the library is . ABS, which is the only one in the 
library. FILEB is to be loaded into a user-controlled partition on a 
mapped system. The name of the partition in which FILEB resides has 
the same name, FILEB, that you specify in the PAR option. The PAR 
option also specifies the base address and the length of the 
partition. Because FILEB is absolute, a base address must be 
specified; here, the base address is 160000. The length in this 
example is 4K bytes. If neither the base nor the length is specified, 
TKB tries to determine the length. The TKB command sequence follows: 

>TKB 

TKB>FILEB/-PI/-HD/LI,FILEB/-SP,FILEB=FILEB.OBJ 

TKB>/ 

Enter Options: 

TKB>STACK=0 

TKB>PAR=FILEB: 16 0000: 40000 

TKB>// 

The next TKB command sequence specifies a shared library called 
FORCOM. FORCOM links to the read-only library called FILEB. You 
build FORCOM with the /LI switch to specify a library to the Task 
Builder. FORCOM is relocatable. You specify in the RESLIB option 
that the resident library to which FORCOM links is called FILEB. The 
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access required is read-only, which /RO specifies in the RESLIB option 
line. The TKB command sequence follows: 

>TKB 

TKB>FORCOM/-HD/LI/PI,FORCOM/-SP,FORCOM=FORCOM.OBJ 

TKB>/ 

Enter Options: 

TKB>STACK=0 

TKB>PAR=FORCOM : : 4000 

TKB>RESLIB=FILEB/RO 

TKB>// 

The next TKB command sequence builds the task and specifies that the 
task links to the library called FORCOM. The RESLIB option line 
specifies the link to the resident library called FORCOM. 

>TKB 

TKB>FOTASK , FOTASK/- SP, FOTASK=FOTASK . OBJ 

TKB>/ 

Enter Options: 

TKB>RESLIB=FORCOM/RW 

TKB>// 

Build the libraries before you build the task, and install the 
libraries before you run or install the task. See Chapters 10 and 11 
for a description of the /PI, /HD, /CO, and /LI switches and the PAR, 
RESCOM, and RESLIB Options. 



5.1.10 Example 5-2: 
MACRO- 11 



Building and Linking to a Device Common in 



A device common is a special type of common that occupies physical 
addresses on the I/O page. When mapped into the virtual address space 
of a task, a device common permits the task to manipulate peripheral 
device registers directly. 



NOTE 

Because any access to the I/O page is 
potentially hazardous to the running 
system, you must exercise extreme 
caution when working with device 
commons. 



The remaining text in this section and the figures associated with it 
illustrate the development and use of a device common. Example 5-2, 
Part 1 shows an assembly listing for a position-independent device 
common named TTCOM. When installed, TTCOM will map the control and 
data registers of the console terminal. Its physical base address 
will be 777500. 
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Example 5-2, Part 1 Assembly Listing for TTCOM 





•TITLE TTCOM 




.PSECT TTCOM, GBL,D,RW,OVR 




.=.+60 


$RCSR: 


.BLKW 1 


$RBUF: 


.BLKW 1 


$XCSR: 


.BLKW 1 


$XBUF: 


.BLKW 1 




.END 



The PDP-11 Peripherals Handbook defines the control and data register 
addresses for the console terminal. In Example 5-2, Part 1, the 
register addresses and the symbol names that correspond to them are as 
follows: 



Register 


Address 


Symbol 


Keyboard Status 


777560 


$RCSR 


Keyboard Data 


777562 


$RBUF 


Printer Status 


777564 


$XCSR 


Printer Data 


777566 


$XBUF 



The double colon (::) following each symbol in Example 5-2, Part 1 
establishes the symbol as global. The first symbol, RCSR, is offset 
from the beginning of TTCOM by 60 (octal) bytes. Each symbol 
thereafter is one word removed from the symbol that precedes it. 
Thus, when TTCOM is installed at 777500, each symbol will be located 
at its proper address. 



Once you have assembled TTCOM, you can build it 
TKB command sequence: 



using the following 



>TKB 

TKB>LB : [1 , 1] TTCOM/-HD/PI , LB : [1 , 1] TTCOM/-WI/SP, LB : [1 , 1] TTCOM=TTCOM 

TKB>/ 

Enter Options: 

TKB>STACK=0 

TKB>PAR=TTCOM : : 100 

TKB>// 

This command sequence directs TKB to create a common image named 
TTCOM. TSK and a symbol definition file named TTCOM. STB. TKB places 
both files on device LB: under UFD [1,1]. The command sequence also 
specifies that TKB is to spool a map listing to the line printer. The 
/SP switch need not be present because it is the default. The /-WI 
switch specifies an 80-column line printer listing format. 



NOTE 

For the command sequence above to work 
in a multiuser protection system, it 
must be input from a privileged 
terminal. 



The STACK=0 option suppresses the stack area in the common's image 
file. The PAR option specifies that the device common will reside 
within a partition of the same name as that of the common. As with 
the data common in Example 5-1 (Section 5.1.7), this is a requirement 
of the RSX-llM system; in an RSX-llM-PLUS system it is not. The PAR 
option also specifies that the base of the common is and that it is 
100 (octal) bytes long. 
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The TKB map for TTCOM that results from the command sequence above is 
shown in Example 5-2, Part 2. The task attributes section of this map 
indicates that the common is position independent and that no header 
is associated with it. The common's image and symbol definition file 
reside on device LB: under UFD [1,1] . 

The map in Example 5-2, Part 2 shows the global symbols defined in the 
common with their relative offsets into the common region. You 
establish the virtual base address for the common and the virtual 
addresses for the symbols within it when you build the tasks that link 
to the common . 

You establish the physical addresses for the common with the MCR 
command SET. The keyword that you use with the SET command depends on 
which system you are running. If your system is. an. RSJf-llM system, 
use the command 

>SET /MAIN=TTCOM:7775:l:DEV 

If your system is one that uses 22-bit physical addresses, use the 
command 

>SET /MAIN=TTCOM: 177775 :1:DEV 

If your system is an RSX-llM-PLUS system, use the command 

>SET /I>AE=TTX;OM: 177775 :1:DEV 

These previous SET command sequences create a main partition named 
TTCOM that begins at physical address 777500 in 18-bit systems and 

physical address 1777750 in 22-bit systems. The partition is one 

64-byte block long, (100 (octal) bytes). The argument DEV identifies 

the partition type. With the common built and the partition for it 

created, you must install TTCOM in an RSX-llM system before using it. 
For example, use 

>INS LB: [1,1] TTCOM 

You can establish the partition for a device common at any time in 
both the RSX-llM and the RSX-llM-PLUS systems. Partitions created to 
accommodate a device common are not a system generation consideration 
because they represent areas of physical address space above memory 
and therefore cannot conflict with memory partitions. 



Example 5-2, Part 2 Task Builder Map for TTCOM 



TTCOM. TSK;1 Memory allocation map TKB M40.10 Page 1 

l-DEC-82 17:02 



Partition name : TTCOM 

Identification : 

Task UIC : [7,62] 

Task attributes: -HD,PI 

Total address windows: 1. 

Task image size : 32. WORDS 



TASK 

ATTRIBUTES 

SECTION 



(continued on next page) 
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Example 5-2, Part 2 (Cont.) Task Builder Map for TTCOM 



Task address limits: 000000 000067 

R-W disk blk limits: 000002 000002 000001 00001. 

*** Root segment: TTCOM 



R/W mem limits: 000000 000067 000070 00056, 
Disk blk limits: 000002 000002 000001 00001. 



Memory allocation synopsis: 
Section 



Title Ident File 



. BLK. : (RW,I,LCL,REL,CON) 000000 000000 00000. 
TTCOM : (RW,D,GBL,REL,OVR) 000000 000070 00056. 

000000 000070 00056. .MAIN. 



TTCOM.OBJ;! 



Global symbols: 

$RBUF 000062-R $RCSR 000060-R $XBUF 000066-R $XCSR 000064-R 

*** Task builder statistics: 



Total work file references: 214. 

Work file reads: 0. 

Work file writes: 0. 

Size of core pool: 6666. WORDS (26. PAGES) 

Size of work file: 768. WORDS (3. PAGES) 

Elapsed time :00 : 00 : 02 

Example 5-2, Part 3 shows an assembly listing for a demonstration 
program named TEST. When built and installed, TEST will print the 
letters A through Z on the console terminal by directly accessing the 
console terminal status and data registers. It will access the status 
and data registers through the device common TTCOM. 



Example 5-2, Part 3 Assembly Listing for TEST 



.TITLE 


TEST 


•IDENT 


/oi/ 


.MCALL 


EXIT$S 


START: MOV 


#15, RO 


CALL 


OUTBYT 


MOV 


#12, RO 


CALL 


OUTBYT 


MOV 


#101, RO 


MOV 


#26.,R1 



START WITH A CARRIAGE RETURN 

PRINT IT 

THEN A LINE FEED 

PRINT IT 

FIRST LETTER IS AN "A" 

NUMBER OF LETTERS TO PRINT 



(continued on next page) 
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Example 5-2, Part 3 (Cont.) Assembly Listing for TEST 



OUTPUT: CALL 


OUTBYT 


; PRINT CURRENT LETTER 


DEC 


Rl 


ONE LESS TIME 


BNE 


OUTPUT 


; AGAIN 


MOV 


#15, RO 


ANOTHER CARRIAGE RETURN 


CALL 


OUTBYT 




MOV 


#12, RO 


; ANOTHER LINE FEED 


CALL 


OUTBYT 




EXIT$S 






OUTBYT: TSTB 


$XCSR 


OUTPUT BUFFER READY? 


BPL 


OUTBYT 


IF NOT WAIT 


MOV 


RO,$XBUF 


• MOVE CHARACTER TO OUTPUT BUFFER 


INC 


RO 


INITIALIZE NEXT LETTER 


RETURN 






.END 


START 





Once you have assembled TEST, you can build it with the following TKB 
command sequence: 

>TKB 

TKB>TEST , TEST/-WI/MA=TEST 

TKB>/ 

Enter Options: 

TKB>C0MM0N=TTC0M:RW:1 

TKB>// 

The COMMON option in this command sequence tells TKB that TEST intends 
to access the device common TTCOM and that TEST will have read/write 
access to it. It also directs TKB to reserve APR 1 for mapping the 
common into TEST'S virtual address space. 



The TKB map that results from the command sequence above is 
Example 5-2, Part 4. 



shown in 



This map contains a global symbols section. TKB included it because 
the /MA switch was applied to the memory allocation file at task-build 
time. Note that the global symbols in this section, which were 
defined in TTCOM, now have virtual addresses assigned to them. The 
addresses assigned by TKB are the result of the APR 1 specification in 
the COMMON= keyword during the task build. 

It is important to remember that programs like TEST, which access the 
I/O page, take complete control of the registers they reference. 
Therefore, coding errors in such programs can disable the devices they 
reference and can even make it impossible for the device drivers to 
regain control of the device. If this happens, you must reboot the 
system. 



5-30 



SHARED REGION CONCEPTS AND EXAMPLES 



Example 5-2, Part 4 Memory Allocation Map for TEST 



TEST.TSK;1 Memory allocation map TKB M40.10 Page 1 

l-DEC-82 17:03 



Partition name : GEN 

Identification : 01 

Task UIC : [7,62] 

Stack limits: 000274 001273 001000 00512. 

PRG xfr address: 001274 

Total address windows: 2. 

Task image size : 384. WORDS 

Task address limits: 000000 001377 

R-W disk blk limits: 000002 000003 000002 00002. 

*** Root segment: TEST 



R/W mem limits: 000000 001377 001400 00768. 
Disk blk limits: 000002 000003 000002 00002. 



Memory allocation synopsis: 

Section Title Ident File 



. BLK. : (RW,I,LCL,REL,CON) 001274 000100 00068. 

001274 000100 00068. .MAIN. TEST.0BJ;1 

TTCOM : (RW,D,GBL,REL,OVR) 200000 000070 00056. 

200000 000070 00056. TTCOM TTCOM. STB;1 



Global symbols: 

$RBUF 020062-R $RCSR 020060-R $XBUF 020066-R $XCSR 020064-R 

*** Task builder statistics: 

Total work file references: 243. 

Work file reads: 0. 

Work file writes: 0. 

Size of core pool: 6666. WORDS (26. pages) 

Size of work file: 768. WORDS (3. pages) 



Elapsed time:00 :00 :03 



5.1.11 Example 5-3: Building and Linking to a Resident Library in 
MACRO- 11 

Resident libraries consist of subroutines that are shared by two or 
more tasks. When such tasks reside in physical memory simultaneously, 
resident libraries provide a considerable memory savings because the 
subroutines within the library appear in memory only once. 
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The text in this section and the figures associated with it illustrate 
the development and use of a resident library, called LIB. 

Example 5-3, Part 1 shows five FORTRAN-callable subroutines: 

• An integer addition routine, AADD 

• An integer subtraction routine, SUBB 

• An integer multiplication routine, MULL 

• An integer division routine, DIVV 

• A register save and restore coroutine, SAVAL 

These subroutines are contained in a single source file, LIB. MAC. 
When assembled and built, they constitute an example of a resident 
library. FORTRAN-callable routines were used in this example so that 
the routines can be accessed by either FORTRAN or MACRO-11 programs. 

Example 5-3, Part 1 Source Listing for Resident Library LIB. MAC 



.TITLE LIB 
•IDENT /Ol/ 



.PSECT AADD,RO,I,GBL,REL,CON 
;** FORTRAN CALLABLE SUBROUTINE TO ADD TWO INTEGERS 



AADD: 



CALL 


$ SAVAL 


• SAVE R0-R5 


MOV 


@2(R5) ,R0 


FIRST OPERAND 


MOV 


@4(R5),R1 


SECOND OPERAND 


ADD 


R0,R1 


SUM THEM 


MOV 


R1,@6(R5) 


STORE RESULT 


RETURN 




RESTORE REGISTERS AND 



•PSECT SUBB,RO,I,GBL,REL,CON 



;** FORTRAN CALLABLE SUBROUTINE TO SUBTRACT TWO INTEGERS 



SUBB: : 



CALL 


$ SAVAL 


MOV 


(a2(R5) ,R0 


MOV 


@4(R5) ,R1 


SUB 


R1,R0 


MOV 


R0,@6(R5) 


RETURN 





SAVE R0-R5 

FIRST OPERAND 

SECOND OPERAND 

SUBTRACT SECOND FROM FIRST 

STORE RESULT 

RESTORE REGISTERS AND RETURN 



.PSECT MULL,RO,I,GBL,REL,CON 

;** FORTRAN CALLABLE SUBROUTINE TO MULTIPLY TWO INTEGERS 

(continued on next page) 
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Example 5-3, Part 1 (Cont.) Source Listing for Resident Library LIB. MAC 



MULL: 



CALL 


$SAVAL ; 


SAVE R0-R5 


MOV 


@2(R5) ,R0 


• FIRST OPERAND 


MOV 


@4(R5) ,R1 


SECOND OPERAND 


MUL 


R0,R1 


; MULTIPLY 


MOV 


R1,@6(R5) 


; STORE RESULT 


RETURN 




; RESTORE REGISTERS AND RETURN 



,PSECT DIVV,RO,I,GBL,REL,CON 



;** FORTRAN CALLABLE SUBROUTINE TO DIVIDE TWO INTEGERS 



DIVV: 



CALL 


$SAVAL 


SAVE REGS R0-R5 


MOV 


@2(R5) ,R3 


; FIRST OPERAND 


MOV 


@4(R5) ,R1 


SECOND OPERAND 


CLR 


R2 


; LOW ORDER 16 BITS 


DIV 


R1,R2 


DIVIDE 


MOV 


R2,@6(R5) 


; STORE RESULT 


RETURN 




• RESTORE REGISTERS AND RETURN 



. PSECT SAVAL,RO,I,GBL,REL,CON 



;**ROUTINE TO SAVE REGISTERS 
$SAVAL: : 



MOV 


R4,-(SP) 


SAVE R4 


MOV 


R3,-(SP) 


SAVE R3 


MOV 


R2,-(SP) 


SAVE R2 


MOV 


R1,-(SP) 


SAVE Rl 


MOV 


RO,-{SP) 


•SAVE RO 


MOV 


12 (SP) ,-(SP) 


COPY RETURN 


MOV 


R5,14(SP) 


;SAVE R5 


CALL 


@(SP) + 


CALL THE CALLER 


MOV 


(SP)+,RO 


; RESTORE RO 


MOV 


(SP)+,R1 


RESTORE Rl 


MOV 


(SP)+,R2 


(RESTORE R2 


MOV 


(SP)+,R3 


RESTORE R3 


MOV 


(SP)+,R4 


; RESTORE R4 


MOV 


(SP)+,R5 


•RESTORE R5 


RETURN 






.END 







Once you have assembled LIB, you can build it with the following TKB 
command sequence: 

TKB>LIB/PI/-HD/LI,LIB/-WI,LIB=LIB 

TKB>/ 

Enter Options: 

TKB>STACK=0 

TKB>PAR=LIB:0:200 

TKB>// 
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This command sequence instructs TKB to build a position- independent 
(/PI) , headerless (/-HD) library image named LIB.TSK. It instructs 
TKB to create a map file LIB. MAP and to output an 80-column listing 
(/-WI) to the line printer. It also specifies that TKB is to create a 
symbol definition file, LIB. STB. TKB creates all three 
files — LIB.TSK, LIB. MAP, and LIB. STB — on device SY: under the UFO 
that corresponds to the terminal UIC. The /LI and /PI switches used 
together cause TKB to name the program section LIB, which is the root 
segment of the library. LIB becomes the only named program section in 
the library. 

If you used the command sequence above without the /LI switch, TKB 
would create a common by default. 

The STACK=0 option suppresses the stack area within the resident 
library's image. The PAR option tells TKB that the resident library 
will reside within a partition of the same name as that of the 
library. As with all shared regions, this is a requirement in an 
RSX-llM" system; | T:n~iam .J^-^ajHCrlf'^ sif#* -^ m addition, 

the PAR option specifies "that the base of the library is and that it 
is 200 (octal) bytes long. (For more information on the switches and 
options used in this example, refer to Chapters 10 and 11.) 

Example 5-3, Part 2 shows the TKB map that results from the command 
sequence above. 

Note in the global symbols section of the map in Example 5-3, Part 2 
that TKB has assigned offsets to the symbols for each library 
function. When the task that links to this library is built, TKB will 
assign virtual addresses to these symbols. 

The program MAIN in Example 5-3, Part 3 exercises the routines in the 
resident library LIB.TSK. When you assemble and build it, MAIN will 
call upon the library routines to add, subtract, multiply, and divide 
the integers contained in the labels OPl and 0P2 within the program. 
MAIN will print the results of each operation to device TI:. 

Example 5-3, Part 2 Task Builder Map for LIB.TSK 

LIB.TSK; 1 Memory allocation map TKB M40.10 Page 1 

ll-DEC-82 13:50 



Partition name : LIB 

Identification : 01 

Task UIC : [7,62] 

Task Attributes: -HD,PI 

Total address windows: 1. 

Task image size : 64. WORDS 

Task address limits: 000000 000163 

R-W disk blk limits: 000002 000002 000001 00001, 

*** Root segment: LIB 



R/W mem limits: 000000 000163 000164 00116. 
Disk blk limits: 000002 000002 000001 00001. 



(continued on next page) 
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Example 5-3, Part 2 (Cont.) Task Builder Map for LIB.TSK 



Memory allocation synopsis: 
Section 



. BLK. 
AADD 

DIVV 

MULL 

SAVAL 

SUBB 



Title Ident File 



LIB 



LIB 



(RW,I,LCL,REL,CON) 000000 000000 00000. 

(RO,I,GBL,REL,C0N) 000000 000024 00020. 

000000 000024 00020. 

(RO,I,GBL,REL,C0N) 000024 000026 00022. 

000024 000026 00022. 

(RO,I,GBL,REL,CON) 000052 000024 00020. 

000052 000024 00020. LIB 

(RO,I,GBL,REL,CON) 000076 000042 00034. 

000076 000042 00034. LIB 

(RO,I,GBL,REL,CON) 000140 000024 00020. 

000140 000024 00020. LIB 



01 



01 



01 



01 



01 



LIB.0BJ;2 
LIB. OB J, -2 
LI3.0BJ;2 
LIB.0BJ;2 
LIB.0BJ;2 



Global symbols: 

AADD 000000-R MULL 
DIVV 000024-R 



000052-R SUBB 



000140-R 



*** Task builder statistics: 

Total work file references: 368. 

Work file reads: 0. 

Work file writes: 0. 

Size of core pool: 7086. WORDS (27. PAGES) 

Size of work file: 768. WORDS (3. PAGES) 

Elapsed time:00:00:03 



Example 5-3, Part 3 Source Listing for MAIN. MAC 



.TITLE MAIN 
.IDENT /Ol/ 



**MAIN - CALLING ROUTINE TO EXERCISE THE ARITHMETIC ROUTINES 
FOUND IN THE RESIDENT LIBRARY, LIB.TSK. 



.MCALL QIOW$S,EXIT$S 



OPl: 


.WORD 


1 


0P2: 


.WORD 


1 


ANS: 


.BLKW 


1 


OUT: 


.BLKW 


100 



OPERAND 1 
OPERAND 2 
RESULT 
FORMAT MESSAGE 

(continued on next page) 
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FORMAT : 


.ASCIZ 
.EVEN 


/THE ANSWER 




.ENABL 


LSB 


START: 








MOV 


#ANS,-(SP) 




MOV 


#0P2,-(SP) 




MOV 


#0P1,-(SP) 




MOV 


#3,-(SP) 




MOV 


SP,R5 




CALL 


AADD 




CALL 


PRINT 




MOV 


SP,R5 




CALL 


SUBB 




CALL 


PRINT 




MOV 


SP,R5 




CALL 


MULL 




CALL 


PRINT 




MOV 


SP,R5 




CALL 


DIVV 




CALL 


PRINT 




EXIT$S 




; + 

;** PRINT - PRINT RESULT OF 


PRINT: 


MOV 


#OUT,R0 




MOV 


#F0RMAT,R1 




MOV 


#ANS,R2 




CALL 


$EDMSG 




QIOW$S 


#I0.WVB,#5, 




RETURN 






• END 


START 



= %D./ 



TO CONTAIN RESULT 

OPERAND 2 

OPERAND 1 

PASSING 3 ARGUMENTS 

ADDRESS OF ARGUMENT BLOCK 

ADD TWO OPERANDS 

PRINT RESULTS 

ADDRESS OF ARGUMENT BLOCK 

SUBTRACT SUBROUTINE 

PRINT RESULTS 

ADDRESS OF ARGUMENT BLOCK 

MULTIPLY SUBROUTINE 

PRINT RESULTS 

ADDRESS OF ARGUMENT BLOCK 

DIVIDE SUBROUTINE 

PRINT RESULTS 



ADDRESS OF SCRATCH AREA 
FORMAT SPECIFICATION 
ARGUMENT TO CONVERT 
FORMAT MESSAGE 
,#40> 
RETURN FROM SUBROUTINE 



Once you have assembled MAIN, you can use the following TKB 
sequence to build it: 



command 



TKB>MAIN,MAIN/MA/-WI/-SP=MAIN 

TKB>/ 

Enter Options: 

TKB>RESLIB=LIB/RO: 3 

TKB>// 



This command sequence 
MAIN.TSK on device SY 
UIC. It also specifi 
The /MA switch reque 
was applied to the de 
the map for the task 
form of the wide lis 
specification to obta 
will not output a map 



instructs TKB to build a task 
under the UFD that corresponds to 
es that TKB is to create a map fil 
sts an extended map format. In this 
vice specification so that TKB would 
the symbols within the library LIB. 
ting switch (/-WI) was appended 
in an 80-column map format. In this 
listing to the line printer 



file named 
the terminal 
e MAIN. MAP. 
example, /MA 
include in 
The negated 
to the map 
example, TKB 



The RESLIB option specifies that the task MAIN is to access the 
library LIB and that it requires read-only access to LIB. TKB uses 
APR3 to map the library. 



The TKB map that results 
Example 5-3, Part 4. 



from this command sequence is shown in 
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MAIN.TSK;! 



Memory allocation map TKB M40.10 
ll-DEC-82 13:51 



Page 1 



GEN 

01 

[7,62] 

000274 001273 001000 00512. 

001634 



Partition name : 

Identification : 

Task UIC : 

Stack limits: 

PRG xfr address: 

Total address w-indows: 2. 

Task image size : 1152. WORDS 

Task address limits: 000000 004327 

R-W disk blk limits: 000002 000006 000005 00005. 

*** Root segment: MAIN 



R/W mem limits: 000000 004327 004330 02264. 
Disk blk limits: 000002 000006 000005 00005. 



Memory allocation synopsis: 



Section 



. BLK. : (RW,I,LCL,REL,CON) 



Title Ident File 



AADD : (RO,I,GBL,REL,CON) 
DIVV : (RO,I,GBL,REL,CON) 
MOLL : {RO,I,GBL,REL,CON) 
SAVAL : (RO,I,GBL,REL,CON) 
SUBB : (RO,I,GBL,REL,C0N) 
$$RESL: (RO,I,LCL,REL,CON) 



001274 


002620 


01424. 










001274 


000530 


00344. 


MAIN 


01 


MAIN.OBJ;! 




002024 


001050 


00552. 


EDTMG 


15 


SYSLIB.OLB; 


1034 


003074 


000216 


00142. 


CBTA 


04.3 


SYSLIB.OLB; 


1034 


003312 


000074 


00060. 


CATB 


03 


SYSLIB.OLB; 


1034 


003406 


000250 


00168. 


EDDAT 


03 


SYSLIB.OLB; 


1034 


003656 


000126 


00086. 


CDDMG 


00 


SYSLIB.OLB; 


1034 


004004 


000110 


00072. 


C5TA 


02 


SYSLIB.OLB; 


1034 


060000 


000024 


00020. 










060000 


000024 


00020. 


LIB 


01 


LIB.STB;17 




060024 


000026 


00022. 










060024 


000026 


00022. 


LIB 


01 


LIB.STB;17 




060052 


000024 


00020. 










060052 


000024 


00020. 


LIB 


01 


LIB.STB;17 




060076 


000042 


00034. 










060076 


000042 


00034. 


LIB 


01 


LIB.STB;17 




060140 


000024 


00020. 










060140 


000024 


00020. 


LIB 


01 


LIB.STB;17 




004114 


000212 


00138. 










004114 


000024 


00020. 


SAVRG 


04 


SYSLIB.OLB; 


;1034 


004140 


000066 


00054. 


ARITH 


03.04 


SYSLIB.OLB; 


;1034 


004226 


000100 


00064. 


DARITH 


0007 


SYSLIB.OLB; 


;1034 



(continued on next page) 
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Example 5-3, Part 4 (Cont.) Task Builder Map for MAIN.TSK 



Global symbols: 

AADD 060000-R 
DIVV 060024-R 
lO.WVB 011000 
MDLL 060052-R 
SUBB 060140-R 
$CBDAT 003074-R 
$CBDMG 003102-R 



$CBDSG 003110-R 
$CBOMG 003116-R 
$CBOSG 003124-R 
$CBTA 003154-R 
$CBTMG 003132-R 
$CBVER 003116-R 
$CDDMG 003656-R 



$CDTB 


003312-R 


$EDMSG 


002122- 


-R 


$COTB 


003320-R 


$MOL 


004140- 


-R 


$C5TA 


004004-R 


$SAVRG 


004114- 


-R 


$DAT 


003452-R 


$TIM 


003532- 


-R 


$DDIV 


004264-R 








$DIV 


004170-R 








$DMUL 


004226-R 









*** Task builder statistics: 

Total work file references 
Work file reads: 0. 
Work file writes: 0. 
Size of core pool: 2066. 
Size of work file: 1024. 



2218. 



Elapsed time: 00: 00: 19 



words (8. pages) 
words (4. pages) 



This map contains a global symbols section. Note that the symbols 
within the library now have virtual addresses assigned to them and 
that these addresses begin at 60000 (octal) , the virtual base address 
of APR 3. The Task Builder's allocation of virtual address space for 
MAIN.TSK is represented diagrammatically in Figure 5-9. 



APR7 — 
APR6 — 
APRS — 
APR4— 
VIRTUAL 60000 APR 3— 
APR2— 
APR 1 — 
VIRTUAL APRO — 



UNUSED 



LIB. TSK 



UNUSED I" 



MAIN. TSK 



y WINDOW 1 REGION 1 



} 



WINDOW REGION 



Figure 5-9 Allocation of Virtual Address Space for MAI 



N.TSK 
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The library LIB is position independent and can therefore be mapped 
anywhere in the referencing task's virtual address space. APR 3 was 
used in this example to contrast this mapping arrangement with the 
mapping of MACCOM in the virtual address space of task MCOMl in 
Example 5-1 (Section 5.1.7). ,If the optional APR parameter in the 
RESLIB option above had been left blank, TKB would have allocated the 
highest available APR to map the library. 



5.1.11.1 Resolving Program Section Names in a Shared Region - As 
described in earlier sections of this chapter, program section names 
within position-independent shared regions must normally be unique 
with respect to program section nam.es vjithin tasks that reference 
them. When a shared region is a position-independent resident common 
and you explicitly declare the program section names within it, 
avoiding program section name conflicts is an easy matter. However, 
when a shared region is a position-independent resident library that 
contains calls to routines within an object module library (SYSLIB, 
for example) , conflicts may develop that are not apparent to you. The 
problem arises when the position-independent resident library and one 
or more tasks that link to it contain calls to separate routines 
residing within the same program section of an object module library. 

When TKB resolves a call from within a module that it is processing to 
a routine within an object module library, it places the routine from 
the library into the image it is building. It also enters into its 
internal table the name of the program section in the object module 
library within which the routine resides. If a position-independent 
resident library contains a call to a routine within a given program 
section of SYSLIB, for example, and then subsequently a task that 
links to the resident library contains a call to a different routine 
within the same program section of SYSLIB, both the resident library 
and the referencing task will contain the program section name. When 
you build the referencing task, the library's .STB file will contain 
the program section name and a program section conflict will develop. 
(Refer to Section 5.1.6 for additional information on the sequence in 
which TKB processes tasks and the potential program section name 
conflicts that can result.) 

This situation and one possible solution to it can be illustrated with 
Example 5-3. When this example was first created, only the arithmetic 
routines were included in the source file of the resident library 
(LIB. MAC in Example 5-3, Part 1). The system library coroutine 
($SAVAL) was resolved from SYSLIB. Because the first instruction of 
each arithmetic routine called $SAVAL, TKB included a copy of it in 
the resident library's image at task-build time. This turned out to 
be unsatisfactory because of a call to the SYSLIB routine $EDMSG (edit 
message) within the program MAIN that links to the resident library. 
Both routines ($SAVAL and $EDMSG) reside within the unnamed or blank 
program section (. BLK.) within SYSLIB. Therefore, a program section 
name conflict developed when MAIN was built. 

To circumvent this problem, the source code for $SAVAL was included in 
the source file for the resident library under the explicitly declared 
program section name SAVAL. 

Another solution would have been to build the resident library 
absolute. In this case, TKB would not have included program section 
names from the resident library into the .STB file for the resident 
library. 
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It is important to note that the above program section name conflict 
develops only when two different routines residing within the same 
program section of an object module library are involved. It presents 
no problem when a resident library and a task that links to it contain 
a call to the same routine in an object module library. In that case, 
TKB copies the routine and the program section name in which it 
resides into the resident library when the library is built. Then, 
when the task that calls the same routine is built, TKB resolves the 
reference to the routine in the resident library instead of in the 
object module library. 



5.1.12 Example 5-4: Building a Task That Creates a Dynamic Region 

In all the examples of tasks shown thus far in this chapter, TKB has 
automatically constructed and placed in the header of the task all of 
the window blocks necessary to map all of the regions of the task's 
image. The INSTALL processor has been responsible for initializing 
the window blocks when the task was installed. In all the examples, 
this has been possible because both TKB and the INSTALL processor have 
had all the information concerning the regions available to them. 

When a task creates regions while it is running (dynamic regions) , the 
information concerning the regions is not available to either the Task 
Builder or INSTALL. Therefore, when TKB builds such a task, it does 
not automatically create window blocks for the dynamic regions. It 
creates only the window blocks necessary to map the task region (the 
region containing the header and stack) and any shared regions that 
the task references. 

Dynamic regions are created and mapped with Executive directives that 
are imbedded in the task's code. When you build a task that creates 
dynamic regions, you must explicitly specify to TKB how many window 
blocks (in excess of those created by TKB for the task region and any 
shared regions) it is to place in the task's header. The Executive 
will initialize these window blocks when it processes the region and 
mapping directives. In all (including window blocks for the task 
region and shared regions), you can include as many as 8 window blocks 
to a task in an RSX-llM system and as'~many"'"as ""16' itv" "an" RSX-iYM-"PLu's 
system. 

The text in the remainder of this section and the figures associated 
with it illustrate the development of a task that creates dynamic 
regions. Example 5-4 shows a task (DYNAMIC. MAC) that creates a 128- 
word dynamic region. This task simply creates an unnamed region, maps 
to it, and fills it with an ascending sequence of numbers beginning at 
the region's base and moving upwards. When the region is full, 
DYNAMIC detaches from it and prints the following message on your 
terminal: 

DYNAMIC IS NOW EXITING 

The region is automatically deleted on detach. 

All of the Executive directives used by DYNAMIC (RDBBK$, WDBBK$, 

DTRG$S, EXIT$S, CRRG$S, CRAW$S, QI0W$S, and QIOW$C) to create and 

manipulate the region are described in the RSX-llM/M-PLUS Executive 

Reference Manual . These directives are SYSGEN options on RSX-llM 
systems. 
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Example 5-4, Part 1 Source Listing for DYNAMIC. MAC 



•TITLE DYNAMIC 

.IDENT /vol/ 

.MCALL RDBBK$,WDBBK$,DTRG$S,EXIT$S,CRRG$S,CRAW$S 

.MCALL QIOW$C,QIOW$S 

.NLIST BEX 



RDB: 



REGION DESCRIPTOR BLOCK 

WORD SIZE OF REGION IN 32 DECIMAL WORD BLOCKS 

WORD 1 REGION NAME 

WORD 2 

WORD 3 NAME OF SYSTEM CONTROLLED PARTITION IN 

WORD 4 WHICH REGION WILL BE CREATED 

WORD 5 STATUS WORD 

WORD 6 PROTECTION WORD 

RDBBK$ 128. , , GEN, <RS .MDL ! RS .ATT ! RS. DEL ! RS .RED ! RS .WRT> , 170017 



WDB: 
MESl: 

ERRl: 

ERR2: 

ERR3: 



START: 



20$; 



WINDOW DESCRIPTOR BLOCK 

WORD APR TO BE USED TO MAP REGION 

WORD 1 SIZE OF WINDOW IN 32-WORD BLOCKS 

WORD 2 REGION ID 

WORD 3 OFFSET INTO REGION TO START MAPPING 

WORD 4 LENGTH IN 32-WORD BLOCKS TO MAP 

WORD 5 STATUS WORD 



WDBBK$ 
.ASCIZ 
SI = . 
.ASCII 
SIZl = 
.ASCII 
SIZ2 = 
.ASCII 
SIZ3 = 
.EVEN 
.PAGE 
•ENABL 

CRRG$S 

BCS 

MOV 

CRAW$S 

BCS 

MOV 

MOV 

.REPT 

ASL 

.ENDR 

MOV 

MOV 

INC 

DEC 

BGT 

T-i m ri /*« /^ ^^ 

u r KV3 9 o 

BCS 

QIOW$C 

EXIT$S 



7,128.,0,0,,WS.MAP!WS.WRT> 

/DYNAMIC IS NOW EXITING/ 
- MESl 

/CREATE REGION FAILED/ 
. - ERRl 

/CREATE ADDRESS WINDOW FAILED/ 
. - ERR2 

/DETACH REGION FAILED/ 
. - ERR3 



LSB 

#RDB 

1$ 

RDB+R.GID,WDB+W. 

#WDB 

2$ 

WDB+W.NBAS,R0 

WDB+W.NSIZ,R2 

5 

R2 

#1,R1 

Rl, (R0)+ 

Rl 

R2 

20$ 

#RDB 



; CREATE A 128 WORD UNNAMED REGION 

; FAILED TO CREATE REGION 

NRID ; COPY REGION ID INTO WINDOW BLOCK 

CREATE ADDR WINDOW AND MAP 

FAILED TO CREATE ADDR WINDOW 

BASE ADDR OF CREATED REGION 

NUMBER OF 32. WORDS IN REGION 

MULTIPLY 

BY 

32. 

INITIAL VALUE TO PLACE IN REGION 

MOVE VALUE INTO REGION 

NEXT VALUE TO PLACE IN REGION 

ONE LESS WORD LEFT 

TO FILL IN 

DETACH AND DELETE REGION 



3$ ; DETACH FAILED 

IO.WVB,5,1,,,,<MES1,S1,40> 



(continued on next page) 
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Example 5-4, Part 1 (Cont.) Source Listing for DYNAMIC. MAC 



r 


ERROR 


ROUTINES 




i$: 


MOV 


#ERR1,R0 


• CREATE FAILED 




MOV 


#SIZ1,R1 


SIZE OF MESSAGE 




BR 


6$ 


WRITE MESSAGE 


2$: 


MOV 


#ERR2,R0 ; 


CREATE ADDRESS WINDOW 




MOV 


#SIZ2,R1 


SIZE OF MESSAGE 




BR 


6$ 




3$: 


MOV 


#ERR3,R0 ; 


DETACH FAILED 




MOV 


#SIZ1,R1 ; 


SIZE OF MESSAGE 


6$: 


QIOW$S 
EXIT$S 
.END 


#I0.WVB,#5,#1,,,, 
START 


<RO,R1,#40> 



FAILED 



Once you have assembled DYNAMIC, you can build it with the following 
TKB command sequence: 

TKB>DYNAMIC,DYNAMIC/-WI/-SP=DYNAMIC 

TKB>/ 

Enter Options: 

TKB>WNDWS=1 

TKB>// 

This command sequence directs TKB to create a task image named 
DYNAMIC. TSK and an 80-column (/-WI) map file named DYNAMIC. MAP on 
device SY: under the terminal UIC. Because /-SP is attached to the 
map file, TKB does not output the file to the line printer. 

Under options, the WNDWS option directs TKB to create one window block 
over and above that required to map the task region. Note that one 
window block must be created for each region the task expects to be 
mapped to simultaneously. 

The map that results from this command sequence is shown in Example 
5-4, Part 2. 

Note that creating dynamic regions always involves the assumption that 
there will be enough room in the partition named in the task's region 
descriptor block to create the region when the task is run. In this 
example, if DYNAMIC were to be run in a system whose partition GEN was 
not large enough to accommodate the region it creates, the CREATE 
REGION directive would fail. 
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Example 5-4, Part 2 Task Builder Map for DYNAMIC.TSK 



DYNAMIC. TSK;1 Memory allocation map TKB M40.10 Page 1 

ll-DEC-82 16:05 



Partition name : GEN 

Identification : VOl 

Task UIC : [7,62] 

Stack limits: 000274 001273 001000 00512. 

PRG xfr address: 001470 

Total address windows: 2, 

Task image size : 512. WORDS 

Task address limits: 000000 001753 

R-W disk blk limits: 000002 000003 000002 00002. 

*** Root segment: DYNAMI 



R/W mem limits: 000000 001753 001754 01004. 
Disk blk limits: 000002 000003 000002 00002. 



Memory allocation synopsis: 
Section 



Title Ident File 

DYNAMIC. OBJ ;1 



. BLK.: (RW,I,LCL,REL,CON) 001274 000430 00280. 

001274 000430 00280. DYNAMI VOl 
$DPB$$: (RW,I,LCL,REL,CON) 001724 000030 00024. 

001724 000030 00024. DYNAMI VOl DYNAMIC. OBJ; 1 



*** Task builder statistics: 

Total work file references: 
Work file reads: 0. 
Work file writes: 0. 



549, 



Size of core pool: 7086. words (27. pages) 
Size of work file: 768. words (3. pages) 

Elapsed time:00:00:06 



5.2 CLUSTER LIBRARIES 

The term "cluster libraries" refers to both a function and a structure 
created by the Task Builder (TKB) that allow a task to dynamically map 
memory-resident shared regions at run time. Cluster libraries permit 
a task to use, for example, a F77CLS library, an FMS-11 library, and 
an FCS-11 library, all mapped through the same task address window. 
The run-time routines put into the task by the Task Builder remap the 
library regions so that, instead of occupying 48K bytes of virtual 
address space, they share 16K bytes of virtual address space. 

One task address window (window 1) maps the libraries into the same 
span of virtual address space (48Kb to 64Kb). TKB maps your task from 
virtual upward. 
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TKB implements the cluster library function in two parts. The first 
part, revectoring of interlibrary calls, is independent of the actual 
remap mechanism but is required for remapping to work. The second 
part executes the required MAP$ directives to map the appropriate 
library. jtl- t- 

The following examples use the library and task structure shown in 
Figure 5-10. Note that in the following examples, the FMS-11/RSX VI 
and FORTRAN-77 software products are sold under separate license and 
are not included with the RSX-llM or RSX-llM-PLUS system. Cluster 
library support may be used with RMS-11 V2.0 or later versions, and 
operates in a fashion similar to the FCS-11 example. Also, the 
particular FCSRES used below is generated by SYSGEN. It consists of 
two PLAS overlays and a null root. 























VIRTUAL 
ADDRESS 


FORTRAN GTS LIBRARY 
F77CLS 




FMS-11 LIBRARY 
FMSOLS 




FCS-11 LIBRARY 
FCSRES 


64KB 
48KB 


































USER 
TASK 







Figure 5-10 Example Library and Task Structure 



5.2.1 Building the Libraries 

You must follow several rules when designing and building shareable 
clustered libraries. The rules are summarized next and discussed in 
detail following the summary. 



5.2.1.1 Summary of Rules for Building the Libraries - 

All libraries but the first require resident overlays. 

User task vectors indirectly resolve all interlibrary 
references. 

• Revectored entry point symbols must not appear in the 
"upstream" .STB file. 

• A called library procedure must not require parameters on the 
stack. 

• All the libraries must be PIC or built for the same address. 

• Trap or asynchronous entry into a library is not permitted. 
The rules are discussed in detail as follows. 
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5.2.1.2 Rule 
Over 
the CLSTR opt 
structures i 
possibly the 
be an overl 
single-segmen 
have a null 
library is no 
structure wi 
specification 



1: All Libraries but the First Require Resident 
lays - The first library is the first named library in 
ion line. To obtain the required run-time overlay data 
n your task, you must define all the libraries except 
first by using memory resident overlays. Although it can 
aid library, the first library need not be and can be a 
t structure. All the libraries, except the first, must 

root if overlaid. You can achieve this in cases where a 
t normally overlaid by creating an unbalanced overlay 
th a null module. For example, the following DDL 

for FMSCLS and a null module would suffice: 



.NAME FMSCLS 

.ROOT FMSCLS-* (NULL, FMSLIB) 

NULL: .FCTR LB : [ 1 ,1] SYSLIB/LB: NULL 

FMSLIB: .FCTR SY:FMSL IB-LB : [1 , 1] FDVL IB/LB 

.END 



;NULL MODULE 
;FMS-11 ROUTINES 



The above ODL specification creates an unbalanced 
shown in Figure 5-11: 



tree in the form 



FMS-11 ROUTINES 












NULL 















Figure 5-11 Example of an Unbalanced Tree with Null Segment 

The effect, after you build your task, is an overlay structure that is 
represented in the Figure 5-12. 

TKB provides the cross-library linkage that it creates from the 
overlay segment data contained in the individual .STB files of each 
library. 



FORTRAN OTS 




FMS-11 ROUTINES 




FCS-11 ROUTINES 


































NULL 






NULL 


































USER TASK 





Figure 5-12 Example of an Overlay Cluster Library Structure 
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5.2,1.3 Rule 2: User Task Vectors Indirectly Resolve all 
Interlibrary References - Figure b-13 below illustrates rule 
2 and is a part of the example in Figure 5-12. In Figure 5-13, if the 
FORTRAN OTS library references an FCS-11 entry point .OPEN, the 
transfer of control from the FORTRAN OTS library to the FCS-11 library 
must be resolved by a jump vector in your task. Or, to state it in 
another way, the CALL instruction in the FORTRAN OTS library must not 
reference directly the target address (the address of .OPEN) in the 
FCS-11 library. The system library contains the modules that perform 
the indirect transfer for FCS-11 based libraries and user tasks. If 
you want to duplicate the indirect referencing mechanism for your own 
purposes. Figure 5-13 and the following text describe the control flow 
for FCS-11. 



FORTRAN OTS 



FCS-11 LIBRARY 





FCSVEC 




.OPEN:: 




Sample code from FCSVEC module: 
OPEN:: MOV #30,-(SP) 



BR 



DISPAT 



STACK OFFSET INTO USER TASK 

JUMP TABLE 

JOIN COMMON DISPATCH 



DISPAT: MOV 


RO,-(SP) 


MOV 


@#.FSRPT,RO 


ADD 


A.JUMP(R0),2(SP) 


MOV 


(SP)+,RO 


MOV 


@(SP)+,-(SP) 


RETURN 





SAVE REGISTER 

GET FCS-11 POINTER 

ADD VECTOR BASE TO OFFSET 

RESTORE REGISTER 

PICK UP ADDRESS OF TARGET 

AND TRANSFER TO TARGET 



Figure 5-13 Example of a Vectored Call Between Libraries 



In this example, the module FCSVEC defines the .OPEN entry point. The 
code at that location stacks an offset or "entry number" and joins 
common dispatch code. The dispatch code, using the low core FCS-11 
impure pointer called .FSRPT, obtains the address of the FCS-11 impure 
data area. At offset A. JUMP in that area is the address of a vector 
of FCS-11 entry points. A return is executed, which transfers control 
to the routine whose address is now on top of the stack. If the 
target routine is an overlaid library, the run-time support ($AUTO) 
loads the appropriate overlay and relays the transfer of control. 

You may use this vectoring mechanism to isolate the linkages between 
two libraries whether or not you use them in the cluster library 
scheme. You can replace either the FORTRAN OTS or the FCS-11 library 
in your system without relinking the other library. However, you must 
relink your task when you replace either of these libraries. 
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5.2.1.4 Rule 3: Revectored Entry Point Symbols Must Not Appear in 
the "Dpstream" .STB File - This rule means that the 
GBLxdL=symbol option must appear for each revectored symbol, as in 
FORTRAN OTS in this example. In the brief example above, the 
following line must appear in the build file for the FORTRAN OTS 
library: 

GBLXCL=.OPEN 



5.2.1.5 Rule 4: A Called Library Procedure Must Not Require 
Parameters on the Stack - This rule applies to routines 
contained in libraries other than the "default" library, as 
represented by the FMSCLS and FCSRES libraries of the above example. 
In addition, the called procedures must use the JSR PC and RTS PC call 
and return convention. The flow of control for a call into a cluster 
library member other than the default proceeds as follows. 

Only your task can call and reference the FCSRES library routine 
.OPEN. All references from other libraries are revectored as 
described above. TKB resolves all such references to an appropriate 
task resident autoload vector. As in the example, when the FORTRAN 
OTS library calls .OPEN, the code revectors the call through your task 
and hence to the autoload vector. At this point, the TKB run-time 
routine $AUTO gets control and searches the overlay segment descriptor 
tree, noting which segments are resident and which must be loaded or 
mapped to access the target routine. 

Next, $AUTO notes that a member of a library cluster must be unmapped 
to comply with the map adjustments required to access the target 
routine. The reference to the unmapped library and the segment within 
the library is placed on the stack, the target library is mapped, and 
the target routine is accessed- through a JSR PC instruction. That 
target routine must not attempt to access parameters by offsets from 
the stack pointer (SP) because of the presence of $AUTO saved 
information. Upon return from the target by an RTS PC instruction, 
the target library is unmapped, and the previous library remapped 
using the saved segment and library data on the stack. Finally, $AUTO 
executes an RTS PC instruction to return to the caller. 

Note that if your task contains a mix of cluster libraries and 
noncluster libraries, the call format rule applies only to control 
transfers to cluster library routines. Other noncluster libraries 
that you create may use any appropriate call and parameter passing 
convention. 



5.2.1.6 Rule 5: All the Libraries Must be PIC or Built for the Same 
Address - TKB must be able to place each library of the 
cluster at the same virtual address. To do this, the libraries must 
be built as position independent or be built to the exact address 
specified in the CLSTR command described below. 



5.2.1.7 Rule 6: Trap or Asynchronous Entry Into a Library is not 
Permitted - A routine built as part of a library that is to 
be used in a cluster may not be specified as the service routine for a 
synchronous trap, or for asynchronous entry as a result of I/O 
completion or Executive service. This restriction is required because 
at the moment of the trap or fault, the appropriate library may not be 
the one that is mapped. For example, if the default library contains 
the service routine to display an error message upon odd address trap 
(the odd address fault occurs within one of the other libraries of the 
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cluster) , the routine will not be available to service the trap. It 
will have been unmapped by the run-time routines to map the called 
library. 

I/O completion and fault service vectors and routines must be placed 
in libraries or task segments that are resident at all times that the 
fault, trap, or I/O completion may occur. 



5.2.2 Building Your Task 

After building the individual libraries and placing the .TSK and .STB 
files for all the libraries into the LB: [1,1] directory, you may build 
your task. The TKB option line that you must use for your task has 
the following syntax: 

CLSTR=library_l,library_2, . . .library_n:switch :apr 

library_n 

The first specification denotes the first or the default library, 
which is the library to which the task maps when the task starts 
up and remaps after any call to another library. 

In an RSX-llM or RSX-llM-PLUS system, the total number of 
libraries to which a task may map is seven. The number of the 
component libraries in clusters is limited to a maximum of six. 
A cluster must contain a minimum of two libraries. It is 
possible to have two clusters of three libraries each or three 
clusters of two libraries each; any combination of clusters and 
libraries must equal at least two or a maximum of six. If six 
libraries are used in clusters, the task may map to only one 
other, separate library. 

:switch:apr 

The switch :RW or :R0 indicates whether the cluster is read-only 
or read-write for this particular task. The APR specification is 
optional and indicates which APR is to be used as the starting 
APR when mapping to cluster libraries. If not specified, TKB 
assigns the highest available APRs and as many as required to map 
the library. 



5.2.3 Examples 

The sample build files for F77CLS, FDVRES, and FCSRES, and for the 
FMS-11 demonstration task FMSDEM are appended as an example of the 
cluster library-build process. 



5.2.3.1 F77CLS — Build the Default Library for the FORTRAN-77 OTS - 

>TKB 

TKB>F77CLS/-HD,F77CLS/CR/-SP/MA,F77CLS=F77RES 

TKB>LB: [1,1]F770TS/LB 

TKB>LB: [1,1]SYSLIB/LB:FCSVEC ; INCLUDE THE FCS JUMP VECTOR 

TKB>/ 

Enter Options: 

STACK=0 

PAR=F77CLS: 140000: 40000 
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FORCE THE JUMP TABLE TO BE LOADED FROM THE SYSTEM 
LIBRARY WHEN THE USER TASK IS BUILT 



GBLINC=.FCSJT 



REFERENCE SYMBOL DEFINED IN 
THE MODULE SYSLIB/LB: FCSJMP 



PREVENT DEFINITIONS FOR FCS-11 ENTRY POINTS FROM APPEARING 
IN THE .STB FILE FOR THIS LIBRARY OR OTHER SYSTEM LIBRARY 



GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
// 



.CLOSE 

.CSIl 

.CSI2 

.DLFNB 

.FINIT 

.GET 

.GETSQ 

.GTDID 

.MRKDL 

.OPFNB 

•PARSE 

.POINT 

.POSRC 

.PRINT 

.PUT 

.PUTSQ 

.SAVRl 

.READ 

.WAIT 



The GBLINC option as shown above forces TKB to add a global reference 
entry in the library .STB file. This ensures that TKB links certain 
modules required by the library, such as impure data areas or 
root-only routines, without further user action. These modules should 
be in the system library (LB: [1 ,1] SYSLIB.OLB) or in a library always 
referenced by your task, so that this forced loading mechanism is 
entirely invisible to you. 



5.2.3.2 FDVRES — Build an FMS-11/RSX VI. Shareable Library - 

TITLE OF THE EXAMPLE COMMAND FILE THAT BUILDS THE FORMS 
MANAGEMENT PLAS-RESIDENT LIBRARY FOR USE WITH THE 
TASK BUILDER CLSTR OPTION. 

FDVRES.CMD 

THE FOLLOWING CODE IS THE EXAMPLE COMMAND FILE: 

LB: [1,1]FDVRES/-HD/MM/SG,MP: [1 , 34] FVRES/MA/-SP, LB : [1,1]FDVRES= 

SY : [ 1 , 24 ] FDVRESBLD/MP 

STACK=0 

PAR=FDVRES: 140000: 40000 

TASK=FDVRES 

THE FOLLOWING LINE FORCES THE FCS JUMP TABLE TO BE INCLUDED IN THE 
SYMBOL TABLE FILE FOR THE FORMS MANAGEMENT LIBRARY. 

GBLINC=.FCSJT 
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THE FOLLOWING LINES FORCE LIBRARY ENTRY POINTS AND DEFINITIONS INTO 
THE TASK ROOT: 

GBLREF=CB$CUR,CB$REV,CB$TST,CB$132,DV$BLD,DV$BLK,DV$DHW,DV$DWD 

GBLREF=DV$GRA,DV$REV,DV$UND,D$ATT1,D$ATT2,D$CLRC,D$FID,D$FXLN 

GBLREF=D$LNCL,D$PICT,D$PLEN,D$RLEN,D$VATT,D$2ATT,D1$ALN,D1$ALP 

GBLREF=D1$ARY,D1$C0M,D1$MIX,D1$NUM,D1$SCR,D1$SNM,D2$DEC,D2$DIS 

GBLREF=D2$FUL,D2$NEC,D2$REQ,D2$RTJ,D2$SPO,D2$TAB,D2$VRT,D2$ZFL 

GBLREF=FC$ALL,FC$ANY,FC$CLS,FC$CSH,FC$DAT,FC$GET,FC$GSC,FC$LST 

GBLREF=FC$OPN,FC$PAL,FC$PSC,FC$PUT,FC$RAL,RC$RTN,FC$SHO,FC$SLN 

GBLREF=FC$SPF , FC$SPN , FC$TRM, FE$ARG , FE$DLN , FE$DNM, FE$DSP, FE$FCD 

GBLREF=FE$FCH,FE$FLB,FE$FLD,FE$FNM,FE$FRM,FE$FSP,FE$ICH,FE$IFN 

GBLREF=FE$IMP,FE$INI,FE$IOL,FE$IOR,FE$LIN,FE$NOF,FE$NSC,FE$STR 

GBLREF=FE$UTR , FE$ INC , FS$SUC , FT$ATB , FT$KPD , FT$NTR , FT$NXT , FT$PRV 

GBLREF=FT$SBK , FT$SFW, FT$SNX , FT$SPR, FT$XBK , FT$XFW, F$ASI Z , F$CHN 

GBLREF=F$FNC , F$IMP , F$LEN , F$NAM , F$NUM , F$REQ , F$RSI Z , F$STS 

GBLREF=F$TRM,F$VAL, IS$ALT, IS$CLR, IS$DEC, IS$DSP, IS$ERR, IS$HFM 

GBLREF=IS$HLP,IS$INS,IS$LST,IS$MED,IS$NMS,IS$SCR,IS$SGN,I$ADVO 

GBLREF=I$ALLC,I$BADR,I$BEND,I$BPTR,I$BSIZ,I$CFRM,I$CURC,I$CURP 

GBLREF=I$DISP,I$DLN1,I$DLN2,I$FADR,I$FBLK,I$FCHN,I$FDES,I$FDST 

GBLREF=I$FDS1,I$FDS2,I$FIXD,I$FMST,I$F0FF,I$F0RM,I$FSIZ,I$FXD1 

GBLREF=I$FXD2,I$HLEN,I$HLPF,I$ILEN,I$IMPA,I$LC0L,I$LINE,I$LLIN 

GBLREF=I$LNCL,I$LPTR,I$LVID,I$NBYT,I$NDAT,I$NFLD,I$PATN,I$PBLN 

GBLREF=I$RESP,I$ROFF,I$STAT,I$STKP,I$SVST,I$VATT,L$CLSZ,L$FDES 

GBLREF=L$LNCL,L$RESP,$$FDVT 

GBLREF=$FDV 

THE FOLLOWING LINES PREVENT THE DEFINITIONS FOR FCS-11 ENTRY POINTS 
FROM APPEARING IN THE FORMS MANAGEMENT LIBRARY .STB FILE: 

GBLXCL=.ASCPP 

GBLXCL=.ASLUN 

GBLXCL=. CLOSE 

GBLXCL=.CTRL 

GBLXCL=.DELET 

GBLXCL=.DLFNB 

GBLXCL=. ENTER 

GBLXCL=.EXTND 

GBLXCL=. FATAL 

GBLXCL=.FCTyp 

GBLXCL=.FIND 

GBLXCL=.FINIT 

GBLXCL=. FLUSH 

GBLXCL=.GET 

GBLXCL=.GETSQ 

GBLXCL=.GTDID 

GBLXCL=.GTDIR 

GBLXCL=.MARK 

GBLXCL=.MBFCT 

GBLXCL=.MRKDL 

GBLXCL=.OPEN 

GBLXCL=.OPFID 

GBLXCL=.OPFNB 

GBLXCL=. PARSE 

GBLXCL=. POINT 

GBLXCL=. POSIT 

GBLXCL=.POSRC 

GBLXCL=.PPASC 

GBLXCL=.PPR50 

GBLXCL=. PRINT 
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GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
// 



. PRSDI 

. PRSDV 

.PRSFN 

.PUT 

.PUTSQ 

.RDFDR 

.RDFFP 

.RDFUI 

•SAVRl 



5.2.3.3 FDVRESBLD.ODL — Overlay Description for FMS-ll/RSX VI. 
Cluster Library - 



THE FOLLOWING LINE IS THE FILENAME OF THE .ODL FILE FOR THE 
PLAS-RESIDENT FORMS MANAGEMENT LIBRARY: 

FDVRESBLD.ODL 

THE FOLLOWING LINES OF CODE ARE CONTAINED IN THE .ODL FILE FOR THE 
PLAS-RESIDENT FORMS MANAGEMENT LIBRARY: 

FDVROT 

FDVROT-*! (MAIN,NULO) 

LB: [1,1]SYSLIB/LB:NULL 

LB: [1 ,1]SYSLIB/LB:FCSVEC 

LB: [1,1]FDVLIB/LB:FDV-LB: [1 ,1] FDVLIB/LB-FCSV 





.NAME 




.ROOT 


NULO: 


.FCTR 


FCSV: 


.FCTR 


MAIN: 


.FCTR 




.END 



5.2.3.4 FCSRES Library Build - FCSRSIBLD.BLD is distributed with the 
RSX-llM and RSX-llM-PLUS distribution kits. Refer to the build 
command and overlay description contained in the files FCSRS1BLD.CMD 
and FCSRSIBLD.ODL, which can be generated by SYSGEN if you want. 



5.2.3.5 F77TST.CMD — File to Build the FMS-ll/RSX VI. FORDEM Test 
Task - 

FORDEM/FP,FORDEM/MA/-SP=FORDEM,HLLFOR 
LB; [1,1]FDVLIB/LB 
LB: [1,1]F770TS/LB 

/ 

EXTSCT=$$FSR1 : 2000 
CLSTR=F77CLS,FDVRES, FCSRES :R0 
STACK=200 
// 



5.2.4 Overlay Run-Time Support Requirements 

The Task Builder uses the .STB files of the cluster libraries to 
obtain the information needed to create the overlay data base. For 
each PLAS overlaid cluster library TKB places autoload vectors, 
segment descriptors, window descriptors, and a region descriptor in 
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the root of the task. This information comprises the overlay run-time 
support for the cluster libraries. In Appendix B, Figure B-9 and the 
accompanying text describe this information. Table 5-1 describes the 
space needed for the overlay run-time system support that includes 
cluster libraries. For a complete description of overlay run-time 
routine sizes, see Section 4.5. 

Using cluster libraries conserves virtual space and may require only 
one window. 



Table 5-1 
Comparison of Overlay Run-Time Wodule Sizes 



Module 



Number 
Program of Bytes 
Section Oct/Dec 



Specific Use 



One of the following modules is included in any overlaid task 
that uses autoload/and in any task that links to a PLAS overlaid 
resident library. f, 



AUTO 
AUTOT 



$$AUTO 122/82. 



$$AUTO 

$$RTQ 

$$RTR 



132/90. 
32/26. 
30/24. 



All tasks that use autoload 

All tasks with AST's 
disabled during autoload 



One of the following modules is included in any overlaid 
conventional task. OVCTR or OVCTC is included in any 
non-overlaid task (conventional or I- and D- space) that links 
to a PLAS overlaid resident library. 



OVCTL $$MRKS 76/62. 
$$RDSG 160/112, 
$$PDLS 2/2. 



Disk overlays only 



OVCTR 



$$MRKS 
$$RDSG 
$$PDLS 



234/156, 

332/218, 

12/10. 



Disk and PLAS overlays with no 
cluster libraries 



OVCTC 



$$MRKS 
$$RDSG 
$$PDLS 



254/172, 
352/234, 
120/80. 



Disk and PLAS overlays 
with cluster libraries 



One of the following three modules is included in any overlaid 
I- and D-space task. 



OVIDL $$MRKS 76/62, 
$$RDSG 224/148. 



$$PDLS 



2/2. 



Disk overlays only 



OVIDR $$MRKS 304/196. 
$$RDSG 502/322. 



$$PDLS 






Disk and PLAS overlays 
with no cluster libraries 



OVIDC $$MRKS 324/212. 
$$RDSG 522/338. 
$$PDLS 120/80. 



Disk and PLAS overlays 
with cluster libraries 



(continued on next page) 
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Table 5-1 (Cont.) 
Comparison of Overlay Run-Time Module Sizes 



Number 
Program of Bytes 
Module Section Oct/Dec Specific Use 



The overlay data vector OVDAT is included in any overlaid task 
and in any task that links to a PLAS overlaid resident library. 

OVDAT $$OVDT 24/20. Included in all tasks 

that perform overlay 
operations 



$$OVDT 


24/20 


$$SGD0 


0/0, 


$$SGD2 


2/2. 


$$RTQ 


0/0. 


$$RTR 


0/0. 


$$RTS 


2/2. 



The overlay error service routine ALERR is included whenever 
OVDAT is included. 

ALERR $$ALER 24/20. Overlay error 



Manual overlay control (LOAD) is used in place of any AUTO 
routine. (See Section 4.2, Manual Load.) 

LOAD $$LOAD 252/170. Manual overlay control 
$$AUTO 14/12. 



5.3 VIRTUAL PROGRAM SECTIONS 



A virtual program section is a special TKB storage allocation facility 
that permits you to create and refer to large data structures by means 
of the mapping directives. Virtual program sections are supported in 
TKB through the VSECT option and in FORTRAN through a set of 
FORTRAN-callable subroutines that issue the necessary mapping 
directives at run time. With the TKB VSECT option, you can specify 
the following parameters for a relocatable program section or 
common block that you have defined in your object module: 

• Base virtual address 



FORTRAN 



Virtual length (window size) 



• Physical length 

By specifying the base address, you can align the program section on a 
4K address boundary as required by the mapping directives. 
Thereafter, references within the program need only point to the base 
of the program section or to the first element in the common block to 
ensure proper boundary alignment. 

By specifying the window size, you can fix the amount of virtual 
address space mar rt^a aixocatea i.u i-ne proyi.am ^«x,v.^uw. *- -.-~ 
allocation made by a module causes the total size to exceed this 
limit, the allocation wraps around to the beginning of the window. 
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By specifying the physical size, you can allocate, before run time, 
the physical memory that the program section will be mapped into at 
run time. TKB allocates this physical memory within an area that 
precedes the task image. This area is called the mapped array area. 

The physical length parameter is optional. If you intend to allocate 
physical memory at run time through the Create Region directive, you 
can specify a value of 0. 

Note that when you specify a nonzero value for the physical memory 
parameter, the resulting allocation affects only the task's memory 
image, not its disk image. 

Note also that TKB attaches the virtual attribute to a relocatable 
program section you have specified in the VSECT option only if the 
section is defined in the root segment of your task through either a 
FORTRAN COMMON or a MACRO-11 .PSECT Statement. The relocatable 
program section with the virtual attribute in the root does not use 
address space in your task; using this procedure merely assigns an 
address, window size, and physical length to a region yet to be mapped 
at run time by your task. For example: 

TKB>VSECT=MARRAY: 160000: 20000: 2000 

In this example, virtual program section MARRAY is allocated with a 

window size of 4K words (20000 (octal) bytes) and a base virtual 

address of 160000. In physical memory, 32K words are reserved for 

mapping the section at run time. 

Assume the program is written in FORTRAN, and includes the following 
statement: 

COMMON /MARRAY/ARRAY(4) . . . 

This statement generates a program section to which TKB attaches the 
virtual attribute. However, this program section is not a FORTRAN 
virtual array. A reference to the first element of the section, 
ARRAY(l), is translated by TKB to the virtual address 160000. 

Figure 5-14 shows the effect of this use of the VSECT option. 

As mentioned previously, TKB restricts the amount of virtual address 
space allocated to the section to a value that is less than or equal 
to the window size, wrapping around to the base if the window size is 
exceeded . 

This process is illustrated in the following example, in which three 
modules. A, B, and C, each contain a program section named VIRT that 
is 3000 words long. A window size of 4K words has been set through 
the VSECT option. If the program section has the concatenate 
attribute, the Task Builder allocates memory to each module as 
follows: 

Length High Limit 

14000 174000 

14000 170000 

14000 164000 

The address limits for modules B and C illustrate the effect of 
address wrap-around when a component of the total allocation exceeds 
the window boundary. Note that the addresses generated will be 
properly aligned with the contents of physical memory if the virtual 
section is remapped in increments of the window size. 
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Module 


Low Limit 


A 


160000 


B 


174000 


C 


170000 
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WINDOW 








APR6 — 






APR 5 — 




TASK 


APR 4 — 




IMAGE 


APRS — 






APR 2 — 


O 


(PROGRAM 

SECTION 

DEFINITION) 


APR 1 — 


COMMON/MARRAY/... 


ADD n 


HEADERS STACK 



} 



©(WINDOW SIZE) 



X 



Q (VIRTUAL BASE ADDRESS) 



VIRTUAL ADDRESS 
SPACE 



TKB>/ 

ENTER options: 

TKB>VSECT=MARRAY:160000:20000:2000 



o e o o 



o 

PHYSICAL LENGTH 
64-BYTE BLOCKS 



■i 



TASK 
IMAGE 



COMMON/MARRAY/. 



HEADER & STACK 



MAPPED 

ARRAY 

AREA 



PHYSICAL MEMORY 

ZK-430-81 



Figure 5-14 VSECT Option Usage 
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5.3.1 FORTRAN Run-Time Support for Virtual Program Sections 

FORTRAN supports subroutines to make use of the mapping directives. 
FORTRAN also supports calls to the following subroutines, which are 
related to virtual program sections: 

Subroutine Function 

ALSCT Allocates a portion of physical memory for use as a 
virtual section 

RLSCT Releases all physical memory allocated to a virtual 
section 

As mentioned earlier, the effect of one or more VSECT= declarations at 
task-build time is to create a pool of physical memory below the task 
image (the mapped array area) . Before a virtual section is referred 
to, the task must allocate a portion of this memory through a call to 
ALSCT. When space is no longer required, it is released through a 
call to RLSCT. 

Note that these subroutines issue no mapping directives. They 
allocate and release space using region and window descriptor arrays 
that you supply. The resulting physical offsets are used in the 
task's subsequent calls that perform the actual mapping. 

The subroutine ALSCT is called to allocate physical memory to a 
virtual program section as follows: 

CALL ALSCT ( ireg , iwnd [ , ists] ) 

ireg 

A one-dimensional integer array that is nine words long. 
Elements 1 through 8 of the array contain a region descriptor for 
the physical memory to be mapped. The descriptor has the 
following format: 

ireg(l) Region ID. 

ireg (2) Size of region in units of 64-byte blocks. 

ireg (3) Name of region in Radix-50 format (first three 
characters) . 

ireg(4) (Second three characters). 

ireg (5) Name of main partition containing region. 

ireg (6) The name is in Radix-50 format. 

ireg (7) Region status word. 

ireg(8) Region protection code. 

ireg (9) Thread word: This element links window descriptors 
that are used to map portions of the region. It is 
maintained by the subroutine. 

The elements of the array that you set up consist of ireg(l) and 
ireg(3) through ireg(8). The thread word, ireg(9), must be on 
the initial call; thereafter, the subroutine maintains it. 
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When your task makes an allocation, ireg(l) and ireg{2) must be 
on the initial call. In this case, ALSCT obtains and stores the 
region size in ireg(2). When the allocation is being made from a 
separate region, the caller must supply both region ID and size. 
The subroutine does not refer to elements 3 through 8 but rather 
the caller must set them up as required by the applicable system 
directives. For a detailed description of these parameters, 
refer to the RSX-llM/M-PLUS Executive Reference Manual. 



iwnd 



A one-dimensional array that is 11 words long. The first eight 
words contain a window descriptor in the following format: 

iwnd(l) Base APR in bits 8 through 15; the Executive sets 
bits through 7 when the appropriate mapping 
directives are issued. 

iwnd (2) Virtual base address. 

iwnd (3) Window size in units of 64-byte blocks. 

iwnd (4) Region ID. 

iwnd (5) Offset into the region, in units of 64-byte blocks. 

iwnd (6) Length to map, in units of 64-byte blocks. 

iwnd (7) Status word. 

iwnd (8) Address of send/receive buffer. 

iwnd (9) Base offset of physical block allocated to section 
in units of 64-byte blocks. 

iwnd (10) Length of block in units of 64-byte blocks (supplied 
by caller) ; set to maximum block offset by 
subroutine. 

iwnd (11) Thread word: This element links window descriptors 
that are used to map other portions of the region. 
It is maintained by the subroutine. 

You must set up IWND (10) before calling ALSCT. 

The following array elements are supplied as output from the 
subroutine: 

iwnd (4), iwnd (5), iwnd (9), iwnd (10), and iwnd (11) 

The remaining elements must be set up as required by the 
Executive directives. Consult the RSX-llM/M-PLUS Executive 
Reference Manual for a detailed description of these parameters. 
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ists 

An area that receives the result of the call. One of the 
following values is returned: 

+1 Block successfully allocated. In this case, the region 
and window descriptor arrays are set up as described 
above. 

-200. Insufficient physical memory was available for 
allocating the block 

The subroutine RLSCT is called to deallocate the physical memory 
assigned to a virtual section as follows: 

CALL RLSCT (ireg,iwnd) 

ireg 

A one-dimensional integer array that is nine words long. The 
contents of the array are the same as those described for 
subroutine ALSCT. 

iwnd 

A one-dimensional integer array that is 11 words long. The 
contents of the array are the same as those described for 
subroutine ALSCT. 

Upon return, element iwnd (10) is the length of the deallocated 
region in units of 64-byte blocks. 

The procedure for using these subroutines can be summarized as 
follows : 

1. You allocate storage in the program for one window descriptor 
per VSECT, and for a single region descriptor. 

2. Your task calls the subroutine ALSCT to reserve the physical 
memory to which the program section will be mapped. 

3. Your task issues the mapping directives to map the virtual 
address space into a portion of the physical memory. It is 
the task's responsibility to ensure that the physical memory 
to be mapped is always within the limits defined by iwnd (9) 
and iwnd (10) . 

4. When the space is no longer required, the task unmaps it and 
releases it with a call to RLSCT. 



5.3.2 Example 5-5: Building a Program that Uses a Virtual Program 
Section 

Example 5-5, Part 1 shows the FORTRAN source file for a task named 
VSECT. FTN. It illustrates the use of the ALSCT FORTRAN subroutine. 
When you build, install, and run VSECT, it will allocate the mapped 
array area below its header, create a 4K-word window, and map to the 
area through the window. ALSCT will then initialize the area and 
prompt for an array subscript at your terminal by printing: 

SUBSCRIPT? 
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When you input a subscript, it responds with ELEMENT= and the contents 
of the array element for the subscript you typed. VSECT continues to 
prompt until you type CTRL/Z. Upon receiving a CTRL/Z, VSECT exits. 

Once you have compiled VSECT, you can build it with the following Task 
Builder command sequence: 

TKB>VSECT , VSECT/-SP=VSECT , LB : [ 1 , 1 ] FOROTS/LB 

TKB>/ 

Enter Options: 

TKB>WNDWS=1 

TKB>VSECT=MARRAY: 16000 0: 200 00: 200 

TKB>// 

This command sequence directs TKB to create a task image file named 
VSECT. TSK and a short (by default) map file VSECT. MAP. Because /-SP 
is appended to the map file, TKB does not output the map to the line 
printer . 

The library switch (/LB) specifies that TKB is to search the FORTRAN 
run-time library FOROTS.OLB to resolve any undefined references in the 
input module VSECT. OBJ. Because the library switch was applied to the 
FORTRAN library file without arguments, TKB extracts from the library 
and includes in the task image any modules in which references are 
defined. 

The WNDWS option directs TKB to add a window block to the header in 
the task image. The Executive initializes this window block when it 
processes the mapping directives within the task. 

The VSECT option directs TKB to establish for the program section 
named MARRAY a base address of 160000 (APR 7) and a length of 
20000 (octal) bytes (4K words). The program section VIRT is defined 
within the task through the FORTRAN COMMON statement. The VSECT 
option also specifies that TKB is to allocate 200 64-byte blocks of 
physical memory in the task's mapped array area below the task's 
header. (For more information on the switches and options used in 
this example, refer to Chapters 10 and 11.) 

The map that results from this command sequence is shown in Example 
5-5, Part 2. 



Example 5-5, Part 1 Source Listing for VSECT. FTN 



C 
C 

C 



VSECT. FTN 

INTEGER *2 SUB, IRDB (9) , IWDB (11) ,DSW 

INTEGER *2 IARRAY(4096) 

COMMON /MARRAY/I ARRAY 

IWDB (1) = "3400 !USE APR 7 FOR WINDOW 

(3) = 128 IWINDOW SIZE = 128*32 WORDS = 4K 

= ! OFFSET 

= "402 ISTATUS = WS . 64B! WS . WRT 



IWDB 

IWDB (5) 

IWDB (7) 

IWDB (10) 



128 



ISIZE TO ALLOCATE 



fcontinued on next nacre) 
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Example 5-5, Part 1 (Cont.) Source Listing for VSECT.FTN 



C 

C ALLOCATE 4K MAPPED ARRAY TO IWDB,IRDB 

C 

CALL ALSCT ( IRDB, IWDB,DSW) 

IF (DSW .NE. 1) GOTO 100 
C 

C CREATE A 4K ADDRESS WINDOW 
C 

CALL CRAW (IWDB,DSW) 

IF (DSW .NE, 1) GOTO 200 
C 

C MAP 4K MAPPED ARRAY 
C 

CALL MAP (IWDB,DSW) 

IF (DSW .NE. 1) GOTO 300 

DO 1 1=1,4096 
1 I ARRAY (I) =1 
C 

C MAPPED ARRAY IS INITIALIZED, PROMPT FOR A SUBSCRIPT 
C 

3 WRITE (5,5) 

5 FORMAT ( '$SUBSCRIPT?') 
READ (5,4,END=1000)S[JB 

4 FORMAT (17) 

WRITE (5,6)IARRAY (SUB) 

6 FORMAT ( • ELEMENT = ',17) 
GOTO 3 

C 

C ERROR ROUTINES 

C 

100 WRITE (5,101)DSW 

101 FORMAT (' ERROR FROM ALSCT. ERROR = ',17) 
GOTO 1000 

200 WRITE (5,201)DSW 

201 FORMAT (' ERROR FROM CREATING ADDRESS WINDOW. ERROR = ',17) 
GOTO 1000 

300 WRITE (5,301)DSW 

301 FORMAT (' ERROR FROM MAPPING. ERROR = ',17) 
1000 CALL EXIT 

END 
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Example 5-5, Part 2 Task Builder Map for VSECT.TSK 



VSECT.TSK;1 Memory allocation map TKB M40.10 

ll-DEC-82 16:12 



Page 1 



Partition Name 
Identification 
Task UIC 



GEN 

FORV02 

[303,1] 

Stack limits: 000300 001277 001000 00512. 
PRG xfr address: 016270 
Total address windows: 2. 
Mapped array area: 4096. words 
Task image size : 8736. words 
Task address limits: 000000 042043 
R-W disk blk limits: 000002 000044 000043 00035. 

*** Root segment: VSECT 



R/W mem limits: 
Disk blk limits: 



000000 042043 042044 17444. 
000002 000044 000043 00035. 



Memory allocation synopsis: 
Section 



. BLK. : (RW,I,LCL,REL,CON) 001300 001160 00624. 

MARRAY: (RW,0,GBL,REL,OVR) 160000 020000 08192. 

160000 020000 08192. 

OTS$F : (RW,I,GBL,REL,CON) 002460 002332 01242. 

002460 000406 00262. 

003066 001724 00980. 

OTS$I : (RW,I,LCL,REL,CON) 005012 011220 04752. 



Title 



Ident File 



.MAIN. FORV02 VSECT. 0BJ;3 

$CONVI F40003 FOROTS. OLB; 2 
$FIO F40006 FOROTS. 0LB;2 



Global symbols: 

ADI$IA 005032-R CAL$ 005140-R ICI$ 022466-R MOI$PS 006050-R 



*** Task builder statistics: 

Total work file references: 27855. 

Work file reads: 0. 

Work file writes: 0. 

Size of core pool: 7086. words (27. 

Size of work file: 4325. words (17. 

Elapsed time : 00 : 00 : 29 



PAGES) 
PAGES) 
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PRIVILEGED TASKS 



6.1 INTRODUCTION 

This chapter discusses privileged tasks: what they are, theii 
possible hazards, how they are mapped, and an example of their usage. 



6.2 PRIVILEGED AND NONPRIVILEGED TASK DISTINCTION 

RSX-llM/M-PLUS systems have two classes of tasks: privileged and 
nonprivileged . The distinction between privileged and nonprivileged 
tasks is primarily based upon system-access capabilities. Because all 
tasks in an unmapped system have access to all of memory, this 
distinction is not hardware enforceable. Therefore, if your system is 
unmapped, your task must be responsible for observing the access rules 
of your system. 

In a mapped system, privileged tasks have special device and memory 
access rights that nonprivileged tasks do not have. A privileged task 
can, with certain exceptions, access the Executive routines and data 
structures; a nonprivileged task cannot. Some privileged tasks have 
automatic I/O page mapping available to them; nonprivileged tasks do 
not. Finally, a privileged task can bypass system security features, 
whereas a nonprivileged task cannot. 



6.3 PRIVILEGED TASK HAZARDS 

Because of their special access rights, privileged tasks are 
potentially hazardous to a running system. A privileged task with 
coding errors can corrupt the Executive or system data structures. 
Moreover, problems caused by such a privileged task can be obscure and 
difficult to isolate. For these reasons, you must exercise caution 
when developing and running a privileged task. 

Make certain that your privileged task has completed its operation 
when you log off the system (type BYE) . BYE does not abort privileged 
tasks as it does nonprivileged tasks because the privileged task may 
be in the process of changing the system data base. Therefore, it 
must be allowed to complete its processing. Also, if the privileged 
task is in system state, neither BYE nor any other task can execute 
until the privileged task completes its processing while in system 
state. However, when the privileged task leaves system state, BYE 
runs and logs you off the system, leaving the privileged task still in 
operation. 



6-1 



PRIVILEGED TASKS 



If a processor trap occurs in a privileged task while the task is in 
user state, the Executive aborts the task. However, if the processor 
trap occurs in the privileged task while the task is in system state, 
the system crashes. However, even while in user state the privileged 
task that is mapped to the Executive can cause a system crash by 
incorrectly changing system data. Please note that a privileged task 
in user state should not be modifying system data. 

All tasks in an unmapped system can access all of memory. The 
privileged or nonprivileged designation has no particular meaning in 
an unmapped system. Therefore, be just as careful about modifying 
Executive, device, or user data in an unmapped system. 



6.4 SPECIFYING A TASK AS PRIVILEGED 

You designate a task as privileged with the /PR (privileged) TKB 
switch (this switch is described in Chapter 10). TKB allocates 
address space for a privileged task based on the memory management APR 
that you specify as an argument to this switch. The argument is 
optional; the default is 5 but you can change it by modifying the 
TKBBLD.CMD file and rebuilding TKB. TKB accepts three arguments: 0, 
4, and 5. Choosing which of these arguments to specify is based on 
the considerations described below. 



6.5 PRIVILEGED TASK MAPPING 

When you specify an argument of 0, your task is marked as privileged 
but not mapped to the Executive or I/O page. Virtual address space 
begins at virtual address and extends upward as far as 32K words. 
Your task cannot access the Executive routines or data structures, and 
TKB does not reserve an APR to map the I/O page. 

When you specify /PR: 4 or /PR: 5, TKB reserves APR 7 for mapping the 
I/O page. Moreover, TKB makes the Executive available to your task by 
reserving the APRS necessary to map the Executive into your task's 
virtual address space. Therefore, if your task requires access to the 
Executive, you must specify an argument of either 4 or 5. However, 5 
is the default. 

The choice between APR 4 and 5 is dictated by the size of the 
Executive area. If the Executive is 16K words or less, you may 
specify an argument of 4 or 5. The value specified depends on the 
task size. A /PR:4 task can be 12K in size and map the I/O page. TKB 
applies a bias of 100000 (16K) to all addresses within your task. 

If the Executive is 20K words, you must specify an argument of 5. TKB 
applies a bias of 120000 (20K) to all addresses within your task. 

The mapping for privileged tasks is shown in Figure 6-1. 

The mapping for APR 4 and 5 is shown in Figure 6-2. 

When you specify an argument of 4, there will be 12K words of address 
space between the beginning of the task and the start of the mapping 
for the I/O page. If your task expects to access the I/O page, it 
must not exceed this 12K-word limit. If it does, TKB uses APR 7 to 
map the task instead of the I/O page. 

When you specify an argument of 5, there will be 8K words of address 
space between the beginning of the task and the start of the mapping 
for the I/O page. In this case, the task must not be greater than 8K 
words if it expects to access the I/O page. 
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Figure 6-1 Privileged Task Mapping 
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Figure 6-2 Mapping for /PR: 4 and /PR: 5 



When a task overlaps the I/O page, TKB does not generate an error 
message. Before TKB generates an error message, a task designated to 
be mapped with APR 4 must be greater than 16K words; a task 
designated to be mapped with APR 5 must be greater than 12K words. 
Only when you install a task that overlaps the I/O page does INSTALL 
generate the following message: 

INS — WARNING — PRIVILEGED TASK NOT MAPPED TO THE I/O PAGE 

While this is not a fatal error message, you should consider the 
condition to be fatal if you expect your task to access the I/O page. 



You can use the /-IP switch to inform TKB that the task 
over 12K and does not need to be mapped to the I/O page, 



is purposely 



A /PR:4 or /PR:5 task can access all of the Executive, system control 
blocks, and I/O page. It can use Executive routines and do logical 
block I/O to a volume that is physically mounted on a device. Also, 
the task can issue a $SWSTK macro to change from user to system state. 
This allows the task to access the Executive or system data structures 
without interruptions or fear of the data being changed while it is 
being accessed. 



6.6 /PR:0 PRIVILEGED TASK 

Using the /PR:0 switch causes TKB to build the task in the same way as 
any other task. Virtual address space begins at virtual address and 
extends upwards as far as 32K minus 32 words. This task cannot access 
the Executive routines and system data structures or directly access 
the I/O page because the Task Builder has not reserved APRs for these 
purposes . 



6-4 



PRIVILEGED TASKS 

There are advantages to using a /PR:0 task and having it mapped into 
APR 0. A /PR:0 task can: 

• Bypass file protection. 

• Use the alter priority (ALTP$) directive. 

• Issue any directive that has a target task. 

• Specify a device name in spawn directives. 

• Write logical block I/O to a physically mounted volume, 
regardless of who issued the Mount or Allocate command. For 
example, the VMR task is a /PR:0 task and writes to mounted 
volumes during the SYSGEN process. However, this advantage 
can be hazardous for obvious reasons. 

A /PR:0 task runs in user state and cannot switch to system state. 
Also, a /PR:0 task is not mapped to the Executive. If you want to 
write a privileged task that does I/O processing, it is advantageous 
to use the /PR:0 switch for your task because there is less chance of 
corrupting the Executive or system code and data. 



6.7 /PR: 4 PRIVILEGED TASK 

If you want your privileged task to map to the Executive and I/O page, 
and your Executive is 16K or less, use the /PR:4 switch in TKB command 
line. If you specify /PR:4 for your task, TKB reserves APR 7 to map 
the I/O page and reserves APRs through 3 to map the Executive as 
part of your task's virtual address space. The /PR: 4 switch can be 
used only if your Executive size is 16K or less, because the 16K 
Executive uses APRs through 3 and your task is assigned mapping that 
starts with APR 4. Therefore, TKB applies a bias of 100000 (16K 
decimal) to all virtual addresses within the task. This specific 
mapping of APRs through 4 and 7 occurs whether the task is in user 
or system state. 

Up to 12K words of virtual address space are possible in a /PR: 4 task. 
The beginning of the task marks the end of the Executive code. If the 
task is 12K words in size, the end of the task marks the start of the 
I/O page. If the task is going to access the I/O page through APR 7, 
the task cannot exceed the 12K limit. If the task does exceed the 
limit, TKB is forced to assign APR 7 to the task code. When building 
the task, TKB does not give you an error message if your task exceeds 
the 12K limit. However, when you install the task, INSTALL sends you 
the following message: 

"INS — WARNING — PRIVILEGED TASK NOT MAPPED TO THE I/O PAGE" 



6.8 /PR: 5 PRIVILEGED TASK 

If you want your privileged task to map to the Executive and I/O page, 
and your Executive is between 16K and 20K, use the /PR: 5 switch in TKB 
command line. If you specify /PR:5 for your task, TKB reserves APR 7 
to map the I/O page and reserves APRs through 4 to map the Executive 
as part of your task's virtual address space. The /PR: 5 switch can be 
used only if your Executive size is between 16K and 20K, because the 
20K Executive uses APRs through 4 and your task is assigned APR 5. 
(APR 5 may be used if the Executive is less than 16K, but this wastes 
virtual address space.) Therefore, TKB applies a bias of 120000 (20K) 
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to all virtual addresses within the task. This specific mapping of 
APRS through 5 and 7 occurs whether the task is in user or system 
state. 
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the I/O page. If the task is 
7, the task cannot exceed the 
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e task, TKB does not give you 

8K limit. However, when you 
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"INS — WARNING — PRIVILEGED TASK NOT MAPPED TO THE I/O PAGE" 



NOTE 

When you use a privileged task, the 
Executive has dedicated almost all the 
APRS to the necessary mapping for the 
Executive, the I/O page, and your task. 
Your task can issue PLAS directives to 
remap any number of these APRs to 
regions. However, such remapping can 
cause obscure and dif f icult-to-f ind 
system bugs. Also, note that when a 
directive unmaps a window that formerly 
mapped the Executive or the I/O page, 
the Executive restores the former 
mapping. 



6.9 EXAMPLE 6-1: BDILDING A PRIVILEGED TASK TO EXAMINE DNIT CONTROL BLOCKS 

The MACRO-11 source program PRIVEX.MAC in Example 6-1 illustrates one 
possible use of a privileged task. 



NOTE 



The nature of a privileged task is such 
that you must have a working knowledge 
of system concepts to understand its 
operation or to write one. If this 
example deals with Executive functions 
that are unfamiliar to you, you may 
prefer to skip this section and return 



i. L. au 



a later time. 



If you assemble, build, and install PRIVEX into your system, it will 
scan the system device tables and examine the UCBs of all nonpseudo 
devices on your system. It will determine whether each device is 
attached by a task and print on your terminal the names of all 
attached devices on your system with the name of each attached 
program. 
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PRIVEX accesses two Executive routines: $SWSTK (switch stack) and 
SSCDVT (scan device tables) . The routine $SWSTK switches the 
processor to system state (kernel mode) . This switch to system state 
is necessary because it inhibits all other processes from modifying 
the Executive data structures until PRIVEX is finished with them. The 
double semicolons (;;) indicate the portion of the task that is 
running in system state. 

The routine $SCDVT performs the actual scanning of the device tables. 
It returns to PRIVEX each time it accesses a new UCB. 

PRIVEX also calls the system library routine $EDMSG (edit message) to 
format the data it has retrieved from the device tables. This routine 
is documented in the IAS/RSX-11 System Library Routines Reference 
Manual . 



Example 6-1, Part 1 Source Code for PRIVEX 



MACRO LIBRARY CALLS 
.TITLE PRIVEX 
.MCALL ALUN$C,EXIT$S,QIOW$S 

LOCAL DATA 

.NLIST BEX 



ATTMES: 


.ASCIZ 


BUFMES: 


.ASCIZ 




.LIST 


QIOBUF: 


.BLKB 




.EVEN 



/%2A%P: IS ATTACHED BY %2R/ 

/BUFFER OVERFLOW/ 

BEX 

132. 



;MESSAGE OUTPUT BUFFER 



BUFFER INTO WHICH INFORMATION IS STORED AT SYSTEM STATE FOR 
PRINTING AT USER STATE. AN ENTRY IS FOUR WORDS LONG: 



ADDRESS IN DCB OF THE TWO ASCII CHARACTER DEVICE NAME 
BINARY UNIT NUMBER 
FIRST RAD50 WORD OF NAME OF ATTACHED TASK 
SECOND RAD50 WORD OF NAME OF ATTACHED TASK 

THE BUFFER IS TERMINATED BY A 

= ALL UNITS IN THE SYSTEM HAVE BEEN EXAMINED 

-1 = THE BUFFER WAS FILLED BEFORE ALL UNITS COULD BE EXAMINED 



BUFFER: .BLKW 4*200. +1 
BUFEND=.-2 



; ADDRESS OF LAST WORD OF BUFFER 



(continued on next page) 
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Example 6-1, Part l(Cont.) Source Code for PRIVEX 



START: MOV #BUFFER,R2 ;GET ADDRESS OF INFORMATION BUFFER 
CLR (R2) ;ASSUME NO UNITS ARE ATTACHED 

CLR Rl ; INITIALIZE CURRENT DCS ADDRESS 



"CALL $SWSTK, FORMAT" SWITCHES TO SYSTEM STATE. ALL REGISTERS 
ARE PRESERVED ACROSS THE TRANSITION FROM USER MODE TO KERNEL 
MODE. BEING IN SYSTEM STATE LOCKS OTHER PROCESSES OUT OF THE 
EXECUTIVE (GUARANTEES THAT THE DATA BEING EXAMINED WILL NOT 
CHANGE WHILE IT IS BEING EXAMINED) . A "RETURN" WILL GIVE 
CONTROL TO "FORMAT" AND WILL RESTORE THE CONTENTS OF THE 
REGISTERS TO THEIR VALUES BEFORE THE "CALL $SWSTK" . 



CALL $SWSTK, FORMAT 

MOV #$SCDVT,-(SP) 

20$: CALL @(SP)+ 

ECS 100$ 



SWITCH TO SYSTEM STATE 

;GET ADDRESS OF SCAN DEVICE TABLES 

;COROUTINE 

;GET NEXT NONPSEUDO DEVICE UCB 

; ADDRESS 

;IF CS NO MORE UCBS 



AT THIS POINT: 

R3 - ADDRESS OF THE DEVICE CONTROL BLOCK 
R4 - ADDRESS OF THE STATUS CONTROL BLOCK 
R5 - ADDRESS OF THE UNIT CONTROL BLOCK 



40$: 



60$: 
80$: 

100$: 



CMP 

BEQ 

MOV 

CLR 

BISB 

MOV 

BEQ 

CMP 

BLOS 

ADD 

MOV 

MOV 

MOV 

MOV 

CLR 

INC 

BR 

CALL 

BCC 

COM 

RETURN 



R1,R3 

40$ 

R3,R1 

RO 

D.UNIT(R3) ,R0 

U.ATT(R5) ,R4 

60$ 

#BUFEND,R2 

80$ 

#D.NAM,R3 

R3, (R2)+ 

RO, (R2)+ 

T.NAM(R4) , (R2)+ 

T.NAM+2(R4) , {R2)+ 

(R2) 

RO 

20$ 

@(SP) + 

80$ 

(R2) 



IS THIS A NEW DCB? 

IF EQ NO 

REMEMBER THIS DCB 

FORM LOWEST UNIT NUMBER ON 

THIS DCB 
IS A TASK ATTACHED? 
IF EQ NO 

IF NE R4 IS TCB ADDRESS 
ANY MORE ROOM IN BUFFER? 
IF LOS NO 

FORM ADDRESS OF DEVICE NAME 
SAVE IT IN BUFFER 
SAVE UNIT NUMBER 
SAVE NAME OF ATTACHED TASK 

ASSUME NO MORE ATTACHED UNITS 
INCREMENT UNIT NUMBER 

GET $SCDVT TO CLEAN OFF STACK 

SHOW BUFFER OVERFLOW 

RETURN TO USER STATE AT FORMAT 



. ENABL 
FORMAT: TST 
BEQ 
CMP 
BNE 
MOV 
CALL 
EXIT: EXIT$S 



LSB 

(R2) 

EXIT 

#-l,(R2) 

40$ 

#BUFMES,R1 

PRINT 



;ANY MORE INFORMATION IN BUFFER? 

;IF EQ NO 

; OVERFLOWED BUFFER? 

;IF NE NO 

;GET ADDRESS OF OVERFLOW MESSAGE 

;PRINT IT 



(continued on next page) 
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Example 6-1, Part l(Cont.) Source Code for PRIVEX 



40$: MOV #ATTMES,R1 
CALL PRINT 
BR FORMAT 



GET ADDRESS OF TEMPLATE 

FORMAT AND PRINT THE INFORMATION 



•DSABL LSB 



PRINT 



INPUTS: 



FORMAT AND PRINT A MESSAGE 



Rl - ADDRESS OF AN $EDMSG INPUT STRING 
R2 - ADDRESS OF AN $EDMSG PARAMETER BLOCK 

OUTPUTS: 

R2 - ADDRESS OF NEXT PARAMETER IN THE $EDMSG PARAMETER BLOCK 
RO, Rl, R3, R4 ARE DESTROYED 
R5 IS PRESERVED 



PRINT: 



MOV 


#QIOBUF,R0 


MOV 


R0,R3 


CALL 


$EDMSG 



;GET ADDRESS OF OUTPUT BUFFER 

;SAVE FOR QIOW$S 

; FORMAT MESSAGE INTO OUTPUT BUFFER 



REMOVE LEADING ZEROS FROM UNIT NUMBER 



20$: 



40$; 



MOV 


R3,R0 


TST 


(R0) + 


MOV 


R0,R4 


DEC 


Rl 


CMPB 


#'0,(R0)+ 


BEQ 


20$ 


INC 


Rl 


CMPB 


#':,-(R0) 


BNE 


40$ 


MOVB 


#'0,(R4)+ 


INC 


Rl 


MOVB 


(R0)+,(R4)+ 


BNE 


40$ 



POINT AT OUTPUT BUFFER 
INCREMENT BY TWO (POINT PAST 

DEVICE NAME) 
REMEMBER THIS SPOT 
ASSUME NEXT BYTE IS A LEADING ZERO 

(REDUCE LENGTH OF MESSAGE) 
IS IT? 

IF EQ YES — IGNORE IT 
COUNTERACT TOO MUCH DECREMENTING 
WAS THE BYTE A COLON (WAS THE UNIT 

NUMBER ZERO) ? 
IF NE NO 

ADD A ZERO UNIT NUMBER 
INCREASE LENGTH OF MESSAGE 
TACK ON REST OF MESSAGE 
IF NE NOT DONE 



PRINT THE MESSAGE ON LUN "OUTLUN" (DEFINED BY THE TASK BUILD FILE) 
AND WAIT USING EVENT FLAG 1 



QIOW$S #I0.WVB,#0UTLUN,#1,,,,R3,R1,#' » ; 

RETURN 

.END START 



PRIVEX. MAC should be assembled with the following assembler command 

5 U JL X H\-j • 

MAOPRIVEX , PRIVEX/-SP=DRO : [ 1 , 1 ] EXEMC/ML , [ 11 , 10 ] RSXMC/PA : 1 , DR2 : [ 30 3 , 1 ] PRIVEX 

The file EXEMC is the Executive macro library and the file RSXMC is 
the Executive prefix file. The switches used in the command string 
are described in the IAS/RSX-11 MACRO- 11 Programmer's Reference 
Manual . 
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The Task Builder command sequence for PRIVEX is as follows: 

>TKB 

TKB> PRIVEX/PR:5,PRIVEX/-SP=PRIVEX 

TKB> DRO: [ 3 , 54 ] RSXllM .STB, DRO : [ 1 , 1 ] EXELIB/LB 

TKB> / 

Enter Options: 

TKB> UNITS=1 ;DEFINE NUMBER OF LUNS 

TKB> GBLDEF=OOTLUN:I ;DEFINE LUN ON WHICH TO PRINT MESSAGES 

TKB> ASG=TI0:1 ;ASSIGN LUN TO DEVICE 

TKB> // 

> 

This command sequence directs TKB to build PRIVEX as a privileged task 
and to add a bias of 120000 to all locations within it. APR 5 was 
chosen in this example because the Executive in the system on which 
this example was originally built is 20K words long. If the Executive 
in your system is 16K words or less, you can use /PR: 4 when you build 
the task. 

In the options section of the TKB command sequence, the UNITS=1 option 
specifies that PRIVEX will use only one logical unit. The 
GBLDEF=0UTLUN:1 option defines the symbol OUTLUN as being equal to 1, 
and the ASG=TI0:1 option associates device TIO: with logical unit 1. 

The TKB map for PRIVEX is shown in Example 6-1, Part 2. The GLOBAL 
SYMBOL SECTION has been shortened to save space. Note that the task's 
address limits begin at virtual address 120000. Figure 6-3 
illustrates how TKB allocates virtual address space for the program. 

Example 6-1, Part 2 Task Builder Map for PRIVEX 

PRIVEX. TSK;1 Memory allocation map TKB M40.10 Page 1 

7-OCT-82 13:26 



Partition name : GEN 

Identification : 01 

Task UIC : [303,1] 

Stack limits: 120230 121227 001000 00512. 

PRG xfr address: 124610 

Task attributes: PR 



Total address windows; 
Task image size 
Task address limits; 
R-W disk blk limits; 



1920. words 

120000 127323 

000002 000011 000010 00008, 



*** Root segment: PRIVEX 



R/W mem limits: 120000 127323 007324 03796. 
Disk blk limits: 000002 000011 000010 00008. 



(continued on next page) 
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Example 6-1, Part 2 (Cont.) Task Builder Map for PRIVEX 



Memory allocation synopsis: 

Section 

. BLK. 



Title 



Ident 



(RW,I,LCL,REL,CON) 121230 005746 03046. 
121230 003656 01966. 
$$RESL: (RO,I,LCI.,REL,CON) 127176 000124 00084. 



PRIVEX 01 



File 



PRIVEX. 0BJ;2 



Global symbols: 

AS. DEL 000001 
D.VOUT 000004 
AS. EXT 000004 
D.VPWF 000006 



BT.UAB 000002 
F.NWAC 000034 
B.DIR 000026 
F.SCHA 000015 



DV.SDI 000020 
lE.DAA 177770 
DV.SQD 000040 
lE.DNA 177771 



D.RS81 177657 



D.RS83 177655 



$PDVTA 020000 
$yHCTB 022674 



$REMOV 054044 
.TT14 023770 



$SGFFR 020652 



$TICLR 041032 



*** Task builder statistics: 

Total work file references: 
Work file reads: 0. 
Work file writes: 0. 
Size of core pool: 13486. 
Size of work file: 12032. 

Elapsed time : 00 : 00 : 51 



250535. 



words (52. 
words (47. 



PAGES) 
PAGES) 



APR 7 

APR 6 

APR 5 

APR 4 

APR 3 

APR 2 

APR 1 

APRO — 



I/O PAGE 



UNUSED 



^^..^.■. . .-^ 



PRIVEX. TSK 



EXECUTIVE 



-VIRTUAL 160000 



VIRTUAL 127147 



VIRTUAL 120000 



■ TASK ADDRESS LIMITS 






■VIRTUALO 



Figure 6-3 Allocation of Virtual Address Space for PRIVEX 
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CHAPTER 7 . 
OSER-MODE I- AND D-SPACE (RSX-11M-PL(JS ONLY), 



This chapter discusses the Task Builder's- ability- to - divide a user 
tasfc into instruction ■arid, data space* (I- arid D-space) '. -A series of 
figures and text- explain task mappirig arid the use of :task. windows in 
an RSX-llM-PLOS . system with an 1-, arid D-space task. In the text,' 
comparisons are made between conventi'bnal; tasks and I- Vand D-space 
tasks. A cohveritional task- is ' one that does riot separately map 
instruction space and darta space. ;;■ 

The I- arid ;D-space feature 'is , an RSX-llM-PLUS' system generation 
/option. : The feature is available only on specif ic processor hardware.. 
Conventional tasks can be run in ,an I- and D-space system, but an I- 
and D-space task cannot run in a systein that does riot have the option, 
■specif ied'.- - . .."■. . ■ .j ■ 



7.1 USER TASK DATA SPACE DEFINED 

User task data space is that space that contains data and which the 
user task .accesses- .through . Dr-'space APRs, _ The function of .1- and 
D-space allows a total of 16 \APRs, to map your task: 8, APRs. for data 
space and 8 APRS for instruction space.. If your task uses both, I- and 
D-space, to its maximum capacity,; it can contain '64K: words , of , 'yirtual 
address space. In. addition .to both- I--: arid D-space,, if -y.our. 'task links 
to a 32K word supervisor-mode library, it can contain ?6K words, of 
virtual 'addreis.s. space,/": "' .'.'.'lJ .- 

To separate the data 'arid instructions , your task .'can use PSECTs'",to 
■contain the . data or,; instructions.- .. .Also,, .your task, can use the. .CRAW$ 
and CRRG.$ directives to dyriamically create -and map to data-space 
regions.' See the RSX-llM/M-PLDS Executive Reference Manual for the 
use of these directives. 

Conventional tasks, and tasks that separate instruction space and data 
space differ in only a few areas, of iriterest^i The next sections 
discuss these areas. 



7.2 I- AND D-SPACE TASK IDENTIFICATION 

Two fields denote an I- and D-space task. In the task header, the 
byte that has the offset H.DMAP identifies the task D-space mapping 

task status word identifies the I- and D-space task to the system. 

The system task Idader or the VMR FIX command initializes these two 
fields at the time the task is loaded. Therefore, tasks built on a 
system other than an I- and D-space system may be run without 
rebuilding on an RSX-llM-PLUS system that supports I- and D-space, 
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The I- and D-space task is one in which TKB separates the data areas 
and instructions. In this task, data areas should be defined by the 
MACRO-11 .PSECT directive that has the data attribute. Similarly, the 
'.PSECT directive with the "I" attribute defines ; instruction areas. 



■7.3 CbMPARISdN OF CONVENTIONAL TA.SKS AND I- AND D-SPACJE TASKS 

A conventional task operating in user mode can contain 32KwQrds .of 
virtual address space and access approximately 32Kwords of physicail 
^'nVeniory, ; However , a task using both I- and D-space APRs can contain; 
6.4Kwbids'of virtual address space and access approximately 64Kwords of 
memory.;.,- -■ '■' ■ \' . , . ■'.<■■•.■-:>■":■ -\ .: ■ .-, 

The. conventdona'l task" in ah I- and D-space system- uses both s&ts of 
'ftPRSi ' However jr the relocation addresses in both l-space and D-space 
APRS are' identical . Also, the task- windows refer to' I-space' APRs in a 
task that does 'not . use D,-space. 

An I- and D-space task can use separately both I- and D-space APRs; 
,that . is, APRs used in this way are not overmapped. Because of this, 
the task can use eight D-space APRs to access and use data , and eight 
I-space' APRS to access and execute instructions. Using 16 APRs allows 
the I- and D-space task to access a total of 64Kwords of physical 
memory at one time. 

Table 7-1 contains a brief mapping summary of the combinations of I- 
and D-space tasks, I- and D-space systems, and the APR mapping that 
occurs. 



Table 7-1 
Mapping Comparison Summary 



I/D 
Task 



I/D 
System 



Mapping Summary 



No 



lgs I-space APRs and D-space APRs contain the same 
relocation addresses. 



No No I-space APRs contain relocation. 

Yes Yes I-space APRs map instruction space. 
APRS map data space. 



D-space 



Yes 



No 



Not possible. 



,7.4 CONVENTIONAL TASK MAPPING 

Conventional tasks map their virtual addresses to their logical 
addresses: through both I-space and .D-space APRs. That is, TKB does" 
not separate instruction space or data space nor does the system 
differentiate- the spaces except by the logic inherent in the task, 
T.herefore, the task must map to its logical address space by both sets' 
of APRS,- which are overmapped. 

Figure 7-1 shows an 8K conventional task linked to an 8K region that 
maps to its logical address space through both D-space and I-space 
APRs in an I- and D-space system. 
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JJSEB-^MODE I- AND D-SPAC& <RSX-11M-PL0S ONLY) 



PHYSICAL 
MEMORY 



D-SPACE 
APRS 



VIRTUAL 

ADDRESS 

SPACE 




jggj:g;ga TASK MAPPING 



Figure 7-i Conventional Task Linked to a Region in ,an 
I- and D-Space System 



7.5 I- AND D-SPACE TASK MAPPING 



figure 7-2 shows an 8 
and instructions in 
-space, the task heade 
task In I-space. TKB 
control in D-space 
task IS' to 'have an e 
'tKe Executive copies 



fflore details, see Figure B-4, 
Task, in Appendix B. 



K I- and D-spac 
this task. Bee 
r must physical 
puts the heade 
Also, the task' 
xternal header 
the header in 



Image 



e task. TKB separated the data 
ause of the way TKB processes task 
ly reside at the beginning of the 
r that the Executive uses for task 
s stack is in D-space. If the 
(under control of the /XH switch) , 
D-space and puts it into the 

on Disk of Overlaid I- and D-Space 



The task shown uses two APRs because of its size (8K) 
maps the task's header and stack and part of D-space. 



D-space APR 
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VIRTUAL 

ADDRESS 

SPACE 



D-SPACE 



HEADER 



D-SPACE 
APRS 



PHYSICAL 
MEMORY 




TASK 
D-SPACE 



STACK 
HEADER 



TASK 
l-SPACE 



.HEADER USED BY 
EXECUTIVE 



UNUSED HEADER 
'COPY 



COPY OF HEADER 
IF EXTERNAL HEADER 



Figure 7-2 I-"and D-space Task, .Mapping in an I- 'and, D-space' Syst.em 
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-,. USER-MODE I-,ftND,T>r-SiPftCE :(RSX-tlM-PLOS ONLY) /,'; 

7.6 TASK WINDOWS IN 1- AND D-SPACE TASKS- . 

TKB uses different windows to map various portions of an I- and 
D-space task. Window in an I- and D-space task cannot.be used 
because it maps the root in I-space. 'Sirailariy, you cannot use window 
1 because: it maps the D-space part of -.the root, . The root of the task > 
which TKB divides into I- and D-space, therefore requires two window^. 
TKB reserves the use of these two windows,- You can specify up to 14 
windows for a task that, useis. I- and ,D-space., ,. ■ 



7.7 SPECIFYING DATA SPACE IN YODR TASK , 

Yoia design an I- and D-,spa<;e task .by. specifying/ data space separately 
from 'instruction \:Space.., ; Goo.d programmitjg' pract 

data ar^as, and,; buffers,' #h6uld.,""be. locateS " ■ in adjacent* locations; 
Simirariy,' all instructions > should be- located, in aid jaceht locations.; 
However, ■ TKB will;. sep^ratfe/an^ data . .space ■ 

,wheh it.;biaild& the task,, ■ ForyTKB; ,to', do- .this., ;you; must use "a method, of 
informing it;.' abo'ut. which : '-statements ■ are ;;data. ; and : which " are 
instructions.;-- j;-^; ",;■ -' -J ./• : ■\.^.: ■'■• ■ ' "c-^ ■\''-*.:J'':- ■.■ ' \' J: ■' '■' ^' ■■ - ■ ''■■//■■.■. " '■' 

For .the MACRO- 11 progr aaiRer ., ' the, way. to .separate data . and. instructions 
is to, : use-the MACRO-ll- .PSEGT directive. 'You can use this, directive 
with the instruction (I); attribute for all the instruction ■ locations 
in your ,' task's „ code. ,- Also, -you ,can.' u'se:;.PSECT and the data {D) 
attribute fox all; the data loca^tlonsi ' .Youmu'st define a. , data .PSECT 
in an I- and D-space task eyen though ho, actual data is contained in 
the task. In this case, the .PSECT can be of 6 length . 

Note that I- .and D-space libraries have not been defined- and are. not a 
possible^ -cprffigurat.iohi.' ' ;;;. ■;'-;'/.-:; .'./. . , .■..--■-■■ ','■..- -. -■' :J../ ••:■.■ -:. 



7^8 OVERLAID I>- AND D-SPACE TASKS ; / 

Except.' for, .the. ',m^ppihg;o,f ah, I-- and; .D-sp'aee ; task- ■ and' the. location ■ of 
instructions; and: data, the;i,- .and- D-spaee^task differs little from a 
cohventibriaX task. ; However, ther,e\'are' structural differences between 
a non-pverlaid and ' ah overlaid I-- and •D--space task. By comparing the, 
two kinds of tasks', the; figures' and text in' , the . ..following ■ sections- 
describe the non-Q'yeElffija /.. and.-pverlaid' i-;\arid " Drspace . tasks , Also., 
you may want. to refer ,to ;the descriptioh ; af ' lOverlaid conventional 
tasks' in' Chapter 3. ' ■' ;" ' 

Figure 7-3 shows a simplified disk image of the 'non-overlaid I- and 
D-space task. , This task contains four I-space P^ECTs and four D-space; 
PSECTs. TKB collects all the I-space PSECTs together in. one .part of, 
the root arid all the D-space PSECTs in another part of the root. 
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USER-MODE I- AND D-SPACE (RSX-llM-PLUS ONLX) 



RELATIVE DISK BLOCK 



RELATIVE DISK BLOCK n 



LABEL BLOCK AREA 



CHECKPOINT AREA 



HEADER (UNUSED) 



ROOT — l-SPACE PART 
INSTRUCTIONS 



HEADER (USER'S) 



STACK 



ROOT — P-SPACE PART 
DATA 



-\ 



> l-SPACE PART 



< 



> D-SPACE PART' 



Figure 7-3 Simplified Disk Image of a Non-Overlaid I- and . 

D-Space Task 



Figure 7-4 shows 
occupied by an ov 
a total physical 
compare Figure 7- 
which shows a con 
occupy the same 
but because they 
different locati 
occupy four PSECT 
data in lAND occu 



the virtual address space and physical memory 
erlaid I- and D-space task called lAND. The task has 
size of 160000 (octal) bytes. (You may want to 
4, which is shown next, with Figure 3-1 in Chapter 3, 
ventional overlaid task.) The instructions and data 
virtual address space and are of equal physical size;, 
are mapped through different APRs, they occupy 
ons in physical memory. The instructions in lAND 
s that have the instruction (I) attribute, and , the 
py four PSECTs that have the data (D) attribute. 



In Figure 7-4, the virtual instruction space contains PSECTs A, B, and 

C, which are those that contain instructions, and ROOT I, which is the 

PSECT in the root that contains instructions. TKB places the unused 
header in I-space part of the root. 

Also, in Figure 7-4, the virtual data space contains PSECTs D, E, and 

F, which are those that contain data, and ROOT D, which is the PSECT 

in the root that contains data. TKB places the task's user header in 
the D-space part of the root. 



As an overlaid task, a possible overlay tree may look, like the 
shown in Figure 7-5. 



one 
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USER-MODE I- AND D-SPACE (RSX-IXM-PLUS 0NLY) 



VIRTUAL l-SPACE MODULES VIRTUAL D-SPACE 



160000 IAPR7 



140000 IAPR6 



120000 IAPR5 



100000 IAPR4 



60000 IAPR3 



40000 IAPR2 



20000 IAPR1 



lAPRO 





















PSECT C 




PSECT B 
PSECT A 




ROOT 1 








UNUSED 
HEADER 



0VR3 
0VR2 
0VR1 



















PSECT G 




PSECT F 
PSECT E 




ROOT D 








USER 
HEADER 





DAPR7 160000 



DAPR6 140000 



DAPR5 120000 



DAPR4 100000 



DAPR3 60000 



DAPR2 40000 



DAPR1 20000 



DAPRO 



Figuire, 7-4 Overlaid I- and D-Space Task Virtual Address Space 



0VR1 



0VR2 



0VR3 



ROOT 

ZK-1 100-82 

Figure 7-5 Example Overlay Tree for Overlaid I- and D-Space Task lAND 



the accompanying ODL statement for this task is: 

.ROOT ROOT-(OVRl,OVR2,OVR3) 

Notice that this ODL statement is not different from any overlaid task 
with this tree structure. In this statement, the module OVRl contains 
the instruction PSECT A and the data PSECT E, the module 0VR2 contains 
the instruction PSECT B and the data PSECT F, and the module 0VR3 
contains the instruction PSECT C and the data PSECT G. Also, the ROOT 
module contains the instruction PSECT I and the data PSECT D. 
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The disk image of this overl 
the instruction and data 
illustrates the difference 
non-overlaid I- and D-space 
the disk image shown in Figu 
segments of the overlaid 
parts. Any autoload vectors 
segments are also included 
for I- and D-space tasks con 
D-space part. TKB places 
part as shown in Figure 7-6. 
tasks are discussed in detai 



aid task, shown in Figure 7-6, contains 

PSECTs in separate areas. Figure 7-6 also 

between disk images of overlaid and 

task disk images when you compare it with 

re 7-3. Notice that TKB separates the 

lAND task into instruction parts and data 

generated because of calls from these 

in the segment area. The autoload vectors 

tain two parts: and T-space part and a 

each part with its corresponding segment 

Autoload vectors for T- and D-space 

1 in Chapter 4. 



RELATIVE BLOCK 



RELATIVE BLOCK 3 



LABEL BLOCK GROUP 
SEGMENT LOAD LIST 



CHECKPOINT AREA 



TASK HEADER (UNUSED) 



ROOT I — INSTRUCTION SPACE 



AUTOLOAD VECTORS FOR l-SPACE 



TASK HEADER (USED) 



TASK STACK AREA 



ROOT D — DATA SPACE 



AUTOLOAD VECTORS FOR D-SPACE 



SEGMENT DESCRIPTORS 



WINDOW DESCRIPTORS 



OVERLAY SEGMENT 0VR1 
l-SPACE PART (PSECT A) 



OVERLAY SEGMENT 0VR1 
D-SPACE PART (PSECT E) 



OVERLAY SEGMENT 0VR2 
l-SPACE PART (PSECT B) 



OVERLAY SEGMENT OVR2 
D-SPACE PART (PSECT F) 



OVERLAY SEGMENT 0VR3 
l-SPACE PART (PSECT C) 



OVERLAY SEGMENT OVR3 
D-SPACE PART (PSECT G) 



:f.igure 7-6 Simplified Disk Image of Overlaid T- and D-Space Task lAND 
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USER-MODE I- AND D-&PACE (RSX-llM-^PIiOS PNLT)' , 

7.8.1 Autoload Vectors and .STB Files 

If your I- and D-space task links to an overlaid shared region, that, 
region must have been built with a version of TKB that supports 
overlaid I- and D-space tasks. The reason for this is that ' the .STB 
files for overlaid shared regions built by older versions, of TKB do 
not contain the ISO records that are needed to create the ■ type of 
autoload vectors that I- and D-space tasks use. 

For newer versions of TKB that support overlaid I- and D-space tasks, 
TKB allocates autoldadable vectors in the root of the task only for 
those entry points in the library referenced by the task. , To create 
the autoload vectors, TKB uses' ISD records in the , STB file when 
linking the task to the library\ if :. the ISD records .are present* 
Therefore, tasks, built with newer versions of TKB tend to be smaller' 
because fewer autoload, vectors, are present. ,, ■/ -. ■ ,, 

For the. Fast Task Builder (FTB) and- older versions of .TKB that do not 
support I-^ and D-space tasks,'- each .■ autoload vector in. the shared 
region's ".STB file,' is allpcafed: in the' root of the t.ask/ being j linked . 
to , the region/ whether- ,or. not ./the,- entry point 'is referenced' byV the 

task.v'.- , .- . . '-■ - ■;■..". ..■■:.■-:■■-".":•.■■■■ 



.■■■■/./.■ V. ■ . .. NOTE '. . .'. ■■.; ;. .■ ■ ..■ 

Libraries created .with older, versions of " 
. TKB do not have the ISD records in the 
■ .STB file that newer versions of TKB use 
to include autoload vectors in the task 
from the .STB file. Therefore, TKB must . • 
create autoload: vectors for every entry 
. '■ ■' point in t.he library. ■,... :.' - : /'.; ;., -.- 

If you are^ using one of these, older' 
. libraries and you. are linking., an .. I- and. 
p-space task to it , 'TKB ■ will , give , you 
../the- fa-tal error message:' ■■- .; ,. ':.- .\.' v . '■.''- ,:[ 

"Module module-name , contains ,, • 
incompatible autoload .vectors" : ' ■; .'.:'; ':'.'/., 

"This message occurs because - the , '.STB " '. : 
file contains . conventional /.autoload ; 
vectors that' are not lisatale. by an- I- and' ..' 
D-space". task. ■' 

For more information about linking shared, regions to I- and D-space 
tasks, see the section in Chapter 5 entitled. Autoload Vectors and 
•STB Files for Overlaid Shared Regions, 



7.9 I- AND D-SPACE TASK MEMORY ALLOCATION AND EXAMPLE MAPS 

The following section discusses and shows the differences between two 
versions of a task that is built both as a conventional task and as an 
I— and D— space task. The conventional task is called MAIN.TSK and the 
I- and D-space version of MAIN.TSK is called MAINID.TSK. Both of 
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these tasks are similar to but not the same as - the task called 
MAIN.TSK shown in Chapter 5. After MAIN.TSK was coded, built, and the 
map printed, MAIN.TSK was rebuilt as an I- and D-space task to create 
MAINID.TSK, To do this, the /ID switch was used in the TKB command 
line. Both versions of this task are overlaid and link to a library. 



7.9.1 Virtual Memory Allocation for MAIN.TSK 

MAIN.TSK has a root called MAIN and three overlay segments called 
INPUT, CALC, and OUTPUT. By comparing the map of this task in Example 

7-1 and the memory allocation diagram in Figure 7-7, you will be able 

to determine the virtual memory space alloc'ition and structure of this 

task. Note that the overlay segments occupy the same virtual address 

space, and the root and segments are mapped in both I-space and 

D-space. - -- 







006307 

OUTPUT 

004514 


005063 

INPUT 




004607 

CALC 


004513 

MAIN 

000000 



006307 

005063 
004607 

004514 
004513 



000000 , 

ZK-1107-82 

Figure 7-7 Memory Allocation Diagram for MAIN.TSK 



7.9.2 Virtual Memory Allocation for MAINID.TSK 

MAINID.TSK has a root called MAIN and three overlay segments. In this 
way MAINID.TSK resembles MAIN.TSK. However, the I-PSECTs and D-PSECTs 
in MAINID.TSK: axf: separated and they are mapped through their 
respective I-space, or D-space APRs . Therefore, MAINID.TSK has two 
virtual address spaces: an I-space and a D-space . Figures 7-8 and 
7-9 show the memory allocation for the I-space and D-space in 
MAINID.TSK. 

The three segments JNPUT, Calc, and OUTPUT occupy the same virtual 
I-space, becausfe these three segments contain instruct*! ons and,, 
therefore, I-PSECTs. : However , the overlay segment OUTPUT is the. only 
segment that occupies virtual D-space because the segments INPUT and 
CALC do not contain data or D-space PSECTs. Note that the. two overlay, 
segments INPUT and CALC have no D-space. You can see this in both 
Figure 7-9 arid the , map in Example 7-2. The map in Example. 7-2 shows 
the virtual .address space allocation for both I-s"acs and D-'s'^ace. ■ 
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USER^MODE I- AND D-SPACE (RSX-llM-PLUS ONLY) 



Ah ~lr^ and '-D-spa'ce.. task uses more virtual memory space than a 
/conyeritionaT task. The map in Example 7-2 shows that MAINID.TSK uses 
1888, / words- of space as opposed to the 1664, words used by MAIN.TSK. 
the reasons for the increase in size of MAINID.TSK over MAIN.TSK are 
■as/ follows:- . 

• An i- and D-space task contains an unused task header. 

,"',: •'Autoload vectors in ah I- and D-space task contain two- more 
".■,"■■■' ,._ words than, conventional, autoload vectors. PSECTs $$ALVD ,and 
' '-/^•;.:$$ALVI in- Example 7-2, contain the autoload vectors,. . You ■ can 

-,.' ' .see from this; map ' that ,they use more' space than the $$ALVC 
,, ■ : PSECt, in /MAINiTSK,. which contains conventional autoload 

'..''■':■-"':■-/- /ivect or s ; ■■■' '-.'[ .'.!.-' ■ '--'■'.' ■ ■ ■■ .. :■.■"■ 



-/*: - The^^ segment ^descriptors .in an overlaid ,r- 
/'/■^c6h€aih .an 'extension.: " ■. - ; 



and ' D-space task 



.in*. a:dditibn to'/thes'e .reasons rf or the. 'increase in/size of ,ah overlaid 
'i^rf ■-/^nd /rB-s^cLce ^ ^'tapk-ij a, memory-re's idervt^O'verlaid ' I-^ and D-space task 
wbuid .be, even -larger : bec^^ the rieesJ for two ■ window descriptors 

'fpr/©ash,iH^raor'y-^reside.nt .segment . -. v ' : , 
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MAIN 

000000 
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003263 
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002714 
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000000 
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-Fi-gure 7-8 Memory Allocation Diagram for MAINID.TSK I-Space 
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002414 
002413 
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MAIN 
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-3 Memory Allocation Diagram for MAINID.TSK D-Space 
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Example 7-1 Map of Overlaid Task MAIN.TSK 



MAIN.TSK;1 Memory allocation map TKB M40.10 

20-OCT-82 10:08 



Page 1 



Task name : 
Partition name ; 
Identification : 
Task UIC : 
Stack limits: 
PRG xfr address; 



...CBP 
GEN 

voo.oo 

[240,1] 

000320 001317 001000 00512. 

002350 

Total address windows: 3. 
Task image size : .1664. words < 
Task address limits: OOOOOO 006307 
R-W disk blk limits: 000002 000012 000011 00009. 



MAIN.TSK;1 Overlay description; 
Base Top Length 



OOOOOO 004513 

004514 005063 

004514 004607 

004514 006307 



004514 02380. 

000350 00232. 

000074 00060. 

001574 00892. 



MAIN 
INPUT 
CALC 
OUTPUT 



MAIN.TSK;! 
MAIN 



Memory allocation map TKB M40.10 
20-OCT-82 10:08 



Page 2 



Root segment: MAIN 



R/W mem limits: OOOOOO 004513 004514 02380. 
Disk blk limits: 000002 000006 000005 00005, 



Memory allocation synopsis; 

Section 

. BLK. : {RW, I,LCL,REL,CON) 

COMl : (RO,D,GBL,REL,CON) 

COM2 : {RW,D,GBL,REL,CON) 

C0H3 : (Rw,D,GBL,ib<EL,CON) 

COM4 : CRW,D,GBL,REL,CON) 

C0M5 : (RW,D,GBL,REL,CON) 









Title 


Ident 


File 


001320 


000466 


00310. 








001320 


000250 


00168. 


EDDAT 


03 


SYSLIB.0LB;5 


001570 


000216 


00142. 


CBTA 


04.3 


SYSLIB.0LB;5 


002006 


000024 


00020. 








002006 


000024 


00020. 


MAIN 


VOO.OO 


MAIN. OBJ; 36 


002032 


000032 


00026. 








002032 


000032 


00026. 


MAIN 


VOO.OO 


MA I N.OB J; 36 


002064 


000010 


00008. 








002064 


000010 


00008. 


MAIN 


VOO . 00 


MAIN. OBJ; 36 


002074 


000234 


00156. 








002074 


000234 


0.0156. 


■MAIN 


VOO . 00 


MAIN.OBJ,-36 


0=02330 


000020 


00016. 









(continued on next paqe) 
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(continued on next page) 
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Example 7-1 (Cont.) Map of Overlaid Task MAIN. TSK 



MAIN.TSKjl Memory allocation map TKB M40.10 Page 5 

20-OCT-82 10:08 



***- Task -builder statistics: 

Total work file references: 13626. 
Work file reads: 0. 
Work file writes: 0. 

Size of core pool: 5198. words (20, pages) 
,. Size of work -file: 4096. words, (16, pages). -,, . : .. ' 

Elapsed time: 00: 00: 19 , - . ;- 

Example 7-2 Map of Overlaid I- and D-Space Task MAIHJD.TSK 



MAINID,TSK;1 Memory allocation map TKB M40.10 Page 1 

15-OCT-82 11:51 



Task name : . . .CBP 
Partition name : GEN 
Identification : VOO.OO 
Task UIC : [240,1] 

Stack limits: 000256 001255 001000 00512. 
PRG xfr address: 000744 
Task attributes: ID 
Total address windows: 4. 

Task image size : 1184. words, I-Space 

704. words, D-Space 
Task Address limits: OOOOOO 004413 I-Space 

OOOOOO 002513 D-Space 
R-W disk blk limits: 000002 000014 000013 00011. 



MAINID.TSK;! Overlay description; 
Base Top Length 



OOOOOO 


002713 


002714 


01484. 


I 


MAIN 


OOOOOO 


002413 


002414 


01292. 


D 




002714 


003263 


000350 


00232. 


1 ■•■ 


INPUT 


002414 


002413 


OOOOOO 


00000. 


-D . 




002714 


003007 


000074 


00060. 


1 


CALC 


002414 


002413 


OOOOOO 


00000. 


D 




002714 


004413 


001500 


00832. 


,!'■■ 


OUTPUT 


002414 


002513 


000100 


00064. 


•'«■'!" 





continued on next page) 
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- Example 7f 2- (Cont.) Map o,f Overlaid I- and D-Space Task MAINID.TSK 



MA.INID.TSK;1 Memory allocation map TKB M40,10 
/MAIN 15-OCT-82 .11:51 



Paqe 2 



*** /Boot segment : MAIN 



.■R/W.nfera / limits : 006000' 002713 .002714 014S4. I-Space 

■;..■'; .: ;' : flOOOOO 002413. 002414 01292. D-Space 

iiW ijik- limitiV' 000 00 2/ 00 00*04^ 00:0003 00003. I-.Space 

,•;;-'- •^./j •, ;■;;,:'. 0,00005 bpO 007 000.003 00003. O-Space 



«ftie*i>r-y .ailocat i.ba sy tiops i s : 
i"Secfet<Sn- >■-.',.. ^~ .:.; "■■■; i-V,"- "-■.'";■ /;- ■ 
'm itK;;J<R», t/LeE,REL,CqfN) ." 

-.Crq^L' ,',J {RO.DiGBtjRfiJ-VCQlfj- 
iGGM? ■'■ . Jr^lR*? KD;GB£.,REt ,CdN)/ .' 
'COfii ■ .■ : fRW-^ D>GBi,^REL>P0N) .■ , 

CqM4 .';: (RW,b/GBL., REL,COKIj ■ 
fCOrtsV J : {RW/D,GBL,REL,cbN} 

LiBROT :' ( RW , T> GBL , REL; COii) ' 
;MI ^if':^; : ^(RO', I » LCL ^REL , CbH>- ;■ 

$.$ALER j'(RO ;' I ,^LCL ,.'RBC , CON ) 



^^ALXTD/cROy D-^I-OLj^REL tCON) 
'.S^^AIii/r^lRO , i i LGILi REL /COij) 



title Ident File 



000256 


000466 


00310. 




000256 


000250 


00168. 


EDDAT 


000526 


000216 


00142. 


GBTA 


001256, 


000024 


00020. 




001256 


000024 


00020. 


MAIN 


0,01302 


000032 


00 026. 




001302 


000032 


00026. 


MAIN 


,001334: 


•oooaio 


00008. 




001334 


,000010 


00008. 


MAIN 


001344 


000234 


00156. 




001344 


000234 


00156. 


MAIN 


001600 


000020 


00016. 




001600 


000020 


00016. 


MAIN 


000000 


000140 


00096; 




000000 


00014,0 


00096. 


LIBRO' 


000744 


000142 


00098. 




0M744 


000142 


00098. 


MAIN 


001106 


000024 


00020. 




001106 


000000 


00000. 


OVIDR 


001106 


000,024 


,00020. 


ALERR 


001620 


000034 


00028. 




001132 


000070 


00056. 





03 SYSLIB.OLB;10 

04.3 SYSLIB.OLBflO 

VOO.OO MAIN.OBJ;34 

VOO.OO MAIN.OBJ;34 

VOO.OO MAI N.OB J; 34 

VOO.OO MAIN.OBJ;34 

VOO.OO MAIN.OBJ;34 

03.01 LIBFSO . STB ; .i 

VOO.OO MAIN.OBJ;34 

01 SYSLIB.OLB;10 
02.00 SYSLIB.OLB;10 



Global symbols: , 

-AA&D ' 0bll52-R N.DTDS 000020 
. ARGBGK" 001316-R N.FAST 000013 



$CBDAT 000526-R $TIM 000402-R 
$CBDMG 000534-R $VEXT 000056 



MAINID.TSK;! 

INP.UT „. 



Memory allocation map TKB M40.10 
15-OCT-82 11:51 



Page 4 



(continued on next page) 
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Example 7-2 (Cont.) Map of Overlaid I- and D-Space Task MAINID.TSK 



Segment: INPUT 



R/W mem limits: 002714 003263 000350 00232. I-Space 

002414 002413 000000 00000. D-Space 

Disk blk limits: 000010 000010 000001 00001. I-Space 

ObOOll 000011 000000 00000. D-Space 



Memory allocation synopsis: 

Section 

. • BLK.: (RW,I,LCL,REL,CON) 

INPUT. l(RO,I,LCL,REL,CON) 

$$ftLVD: (RO,D,[.CL,REL,CON) 
$$ALVI: (RO,I,LCL,REL,CON) 
$$RTS :(RO,I,GBL,REL,OVR) 
$$SLVC: (RO,I,LCL,REL,CON) 



Title Ident File 



002714 000074 00060. 

002714 000074 00060. CATB 03 

003010 000252 00170'. 

003010 000252 00170. INPUT 01 

002414 OOOOOO 00000. - 

003262 OOOOOO 00000. 

002710 000002 00002. 

003262 OOOOOO 00000. 



SYSLIB.OLB;10 
INPUT. OBJ; 32 



Global symbols: 

INPUT 003010-R $CDTB 002714-R $COTB 002722-R 



MAINID.TSK;! Memory allocation map TKB M40.10 Page 5 
CALC 15-OCT-82 11:51 



*** Task builder statistics: 

Total work file references: 13920. 
Work file reads: 0. 

'/'■ 'Work ".■^'illilfe-i writes : ^.0. ■ ■■ 

Size of •■tore' pool: 50^10. Jyords' (IJ, 'pages) 
_ Size of,:Work filf;: 4096; words (16. pages) 

;;,;J'iJap^:ei3S%i»&;;^ 
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CHAPTER 8 
SUPERVISOR-MODE LIBRARIES (RSX-llM-PLUS ONLY) 



A supervisor-mode library is a: resident" library that doubles a user', 
task's virtual , address = spaq'e by mapping the .instruction space of the' 
processor's supervisor mode. Supervisor-mode litsraries are /available 
-only on RSX-llM-PLUS systems-running on PbP-ll'/44s and PDP-ll/70s. ■ 



8.1 INTRODOCTION 

A call from within a user task to a subroutine within a; 
supervisor-mode library causes the processor tO: switch from user to 
supervisor mode. The user task transfers control to a mode-^switching, 
vector that TKB includes within the task. The mode-switching vector 
performs the mode switch and then transfers control to the called 
subroutine within the supervisor-mode library. The library routine 
executes with the processor in supervisor mode., When the library 
routine finishes executing, it transfers control to a completion 
routine within the library. The; completion routine mode switches tJie 
processor back to user mode. The user task continues execatihg with' 
the processor in user mode at the return address on the stack. This 
process recurs whenever the user task calls a subroutine in the 
/supervisor-mode library. 



■8.2 MODE-SWITCHING VECTORS . •^, , ,\A': 

In a task 'that, links to 'a supervi'sor-mode , 1-ibraryj TKB ' includes ; a 
, 4-word,' mode-s witching vector in the user /task's address space for 
each entry point referenced of a subroutine in the library. / 

The following shows the contents of a mode-switching vector: 

MOV #COMPLETION-ROUTINE,-(SP) 

CSM #SUPERVIS0R-MODE-RO0TINE ADDRESS , 



NOTE 

When mode switching from user to 
supervisor mode, all registers of the 
referencing task are preserved. All 
condition codes in the PS saved on the 
stack are cleared and must be restored 
by the completion routine. 
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&; 3 COMPLETION ROUTINES 

After 'the siibr oat ine' finishes executing, its RETURN statement 
transfers • control to a. completion routine that mode-switches from the 
supervisor Lo user mode. The . completion routine returns program 
control back to the referencing taisk at ^ the- instruction after the call 
to the subroutine. There are two completioh routines in SYSLIB: 

• $CMPCS restores only the carry bit in the: user-mode PS, 

• $CMPAL restores all the conditioh cod-e/blts in the user-mode 
PS. 



8.4 RESTRICTIONS ON THE CONTENTS OF SOPERVISOR-MODEL 

The following restrictions 'ar,e\; 'placed ■ oh ''the ;; conteht^^^ of a 
supervisor-mode library: ' ' J ' " . V ' : " ' " 

• Only subroutines using • the form; JSR PC, -x should be used 
"l~ 'wl-thiis the. ;lxbrary.' " - "j •"'-.'". ' ■ ' "' 

, • The library must not contain' subroutines that use the stack to 
pass jiarameters,. 

• If both the library' and the referencing task, link to a 
subroutine from SYSLIB, then the entry point name of the 
subroutine must be excluded from the .STB file for the 
library. 

• Unless you include the MSDS$ directive within the library, the 
library must not contain data of any kind (even R/0) because 
the user supervisor D-space APRs map the user task by default. 
This includes user data, buffers, I/O status blocks, and 
directive parameter blocks (only the $S directive form can be 
used, because the DPS for this form is pushed onto the user 
stack at run time). 

Using the Map Supervisor D-space Executive Directive (MSDS$) , 
the' library can map data within the instruction space of the 
supervisor-mode library by using the supervisor D-space APRs. 
The directive maps specific supervisor D-space APRs to 
supervisor instruction space by copying the supervisor I-space 
APRS that map the data portion of the library. To effectively 
contain data within a supervisor-mode library, you must know 
which APRs map the data portions of your task and library. 

NOTE 

, You cannot use MSDS? to map-supervisor 
D-space APR 0, Mapping library data and 
,;■•-./' the user task simultaneously should be 
done with /extreme care. Section 5.3,4,2 ; 
'-'•:.■"'-..;; of; the . RSX-11h/M-PL0S ,' Executive / 

' • . " Reference ' Manual discusses the' MSDS$ 
■.'..'-•: '..J': -■■ ^ . directive in detailj .' '. ■' ^"'-- - .". ■ ■ ; 
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8.5 SUPERVISOR-MODE LIBRARY MAPPING 

Supervisor-moiio libraries arc mappjed with the supervisor I-space APRs . 
Supervisor D-space APRs can map the user task, data within the 
library, or both the user task and library data sitnul tanoously . They 
ranp the user task by dofault. 

The supervisor D-space APRs can be .-n.jpped differently according to 
whether the library contains data. 

Supervisor D-space APRs are copies of user T-spaco APRs, which map the 
entire usnr task. This gives the library access to data within the 



3.5.1 Supervisor Mode Library Data 

Libraries that contain data require extremely complicated mapping that 
may overwrite the user task or cause the task to fail. 

Supervisor D-space APRs are copies of user I-space APRs, which :iiap the 
entire user task. For I- and D-sp<.Jce t^isks, the supervisor D-spaces 
APRS are copies of the user D-space APRs. Including the MSDS$ 
Executive directive (see Section 8-4) within the library code enables 
the library to map data within its own instruction space. The user 
task may be overmapped. The library has access to data within its 
instruction spoce /snd to d.=ita in the UFser t.Tsk that is not overmapped 
by the MSDS.? directive. 

Figure 8-2 illustrates this mapping. 



8.5.2 Supervisor Mode Libraries with I- and D-Space Tasks 

I- and D-space tasks may link to supervisor-mode libraries. Instead 
of mapping to tho entire user task, the supervisor-mode library's 
D-space APRS map the task's data space. Because the I- and D-space 
task maps its data with the D-space APRs, the task's D-space APRs are 
copied into the auporvisor-mode library's D-space APRs. Therefore, 
the: supervisor-mode library maps its own instructions with 
supervisor-mode I-space APRs and maps the task's data with 
supervisor -mode D-space APRs. 

Figure 8-3 illustrates the mapping of an I- and D-space task linked to^ 
a supervisor mods librarv. 



8-3 



USEF1 
D-SPACE 



USEF^ 
-SPACE 



00 



SUPERVISOR 
D-SPACEE 



SUPERVISOR 
l-SPACE 




256K 



24 K 
USER 
TASK 



16K 

SUPERVISOR 

LIBRARY 



CO 
G. 

W 
» 
< 

M 

M 
O 
50 
I 

o 
o 



CO 

M 

w 



w 
w 

I 



a 

CO 

o 

ES 



APR MAPPING 
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Figure 8-1 Mapping of a 24K Conventional User Task That Links to a 

16K Supervisor-Mode Library 
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APR MAPPING 

UNUSED 

0-4 map entire user task 

0-1 and 3-4 map user task 

2 remapped to supervisor data using MSDS$ 

0-2 map library 



Figure 8-2 Mapping of a 20K Conventional User Task That Links to -i 
12K Supervisor-Mode Library Containing 4K of Data 
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APR MAPPING 
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Figure 8-3 Mapping of a 40K I- and D-Space Task That Links 
to an 8K Supervisor-Mode Library 



' .: SpPERVrSOR-MOpE LIBRARIES (RSX-11M-; Ftps pNty) ' 

8.6 BOILtJING AND LINKING; TO, SDPERVISOR-MOpE: LIBRARIES. 

Building and linking to • a supervisor-mode- liorary is essentially the 

samei as building and linking/to a- conventional resident library 

(discussed in Cbapter 5) . When you build a supe'rvisbr-mode library, 
you suppress the header by attaching /--HD to the 'task image file. 
During option input , you . suppress the .stack area by specifying'; 
STACk=0. Tou specify the partition in which the library is to reside, 
and, optionally^, the- base address and'. length of the library with' the 
PAR .option,. ■ ■/ - / -.. .-■"■.■ ; / :'".:'' •'.■"■'.:••'..-''■■' 



8V6yL ■. .Rel,eyajit..-tKB\: Opt ions ■.■■■''.\ . :■■'.■' :////'.'' ■.■:'/■':[ '. } ■'..■^'".v^ '.■:.^'-' /'■'■'',;.■:" ■,/ 

.Usef.the/folLowi,ng .Voptiohs: . ta , toui-iia- ^ ■'.^'^ ,0 ''^^^'^^f^'?^ ;. s^uperHsioi-iftode,:'; 

^libraries;-, ■;:■,■'.}''> '.■/..■./■ "/':■ .'/, ^'■'■'■^~'' '■/',■:■ •'-'.■:■''.' :-'-'/ ''f.'/.-'i- :'...''■. :■,■ -■ " ' -"~.: .-'..: r' '.' 

:^:'y::/.CMV'S^:y. :'(:':','.:''/ Vs.r'r j-lnd iqates ''::',/ tfKaf; /'V_-ybu->%'ar^;"Vj;.;.buiilding: 
■■■-'"/";.■■ ■ ;'■'-■■- .'■■^'.::-'. ■'■,.,' 'V';- super Y-isor^ihoda'.^'libE^kiry..^ rarid.^'BpeCJi.f i«S".;,"theL* 
; '■-"'. -^'^ .■■""'; ■■'■■,■- ■;.■■■-■. ' ■■''."■'.'name.- of; t^he- 'eoinplefeioh' jroutirie-. 'J;'-'-'. ■■" '^';■■'■■ 
. ?. RESStiP (SyPLIB).. ;, Indicates that your,; .t^tsk/; references & 
'. ■. '.."'- ■■'■'■ , ■■ , ' ■ ". -■■ . superviso]:-mpde;'iIbtary-.,.V:' -'^ ',■-..'":■ '■v; :-' ".:-,'V .■'.'■■ -'; 

GBLXGL~- Iv : • ;; -'/ /'i:x,cluaes./a .gXpbal'^s^^ 
\ . •:' ; of the superviSQ,r.Hmbde'_iibrafy. ' v 

These ,; options -are d i scussed briefly betlbw. and are fully .dpqumented . i ri 
Chapter ■ 11,' ■ . . .■ 



8.6.2 Building the Library . 

You rindicabe to the. Task' Bui,id,er that ^ ■ yo,u are ,. building a 
supervisor-mode -library with ; the CMP,R.T optibn- The argument 'for this 
option,' ide,ntif ies-; th^^.entry ^syraboi. ;of t;fie;».>CGmpletion ' y rauti,ne. ,'/^ - Wl^eh , 
th^:' Task " . Bui Id-erv,,- processes' ^: this. /O option ,' '; it- .p^f^eesv ;trhe-;comple;tion. 
r,ojjtaheeritry -point In the library's. ''STB ^tilev- ,To;' ,'exc;lude,'Va-v global 
symbol,' ' from ' ' ttte 'libraxy ''S ■'■■' .STB: v-file:^,-';you.;' specify- the;name'';bf' the 
.gIo,bai.' symbol, as the argument of the; GBIiXCL' , bption,.;- You ' must exclude 
from" the, 'iSTB ''file\pf -a superyisorr-mbde.;i 
;t% ;. library ;';that/'.repr ^sents';,/tlie' -^ fall pwihg 

. •; An entry point .to a stibroutine' that, uses' the. y stack to ' pass 
■parameters , ./\-'\.''' 

: An entry point to a .subroutine mapped' in 'user itiode that the, 
referencing user task calls 



8.6.3 Building the Referencing Task 

When you build a task that references a supervisor-mode library, use 
the RESSUP option if you are referencing a user-owned, supervisor-mode 
library and SUPLIB if you are referencing a system-owned, 
supervisor-mode library. (Like the RE3LIB - and LIBR options j-or 
linking to conventional libraries, RESSUP and SUPLIB are functionally 
the same.) The arguments for these options are: 

• The filespec (RESSUP option) or name (SUPLIB) of the library 
to be referenced 



8-7 



SUPERVISOR-MODE LIBKAP.IiJis (KSX-llM-FiiOSi ONLY) 

• A switch that tells TKB whether to use system-supplied vectors 
to perform mode switching from user to supervisor mode, 

• For position-independent libraries, the first available 
supervisor-mode I-space APR that you want to map the library. 



8.6.4 Mode Switching Instruction 

Mode switching occurs with a new instruction available on the 11/44 
and emulated by the Executive on the 11/70. Throughout the remainder 
of the chapter, supervisor-mode libraries are referred to as CSM 
(change supervisor mode) libraries. 



8.7 CSM LIBRARIES 

This section discusses how you build and link to CSM libraries. It 

also shows an extended example of building and linking to a CSM 

library and explains the context-switching vectors and completion 

routines for CSM libraries. 



8.7.1 Building a CSM Library 

You indicate to the Task Builder that you are building a CSM library 
by specifying the name of the completion routine as the argument for 
the CMPRT option. This option places the name of the completion 
routine into the library's .STB file. Link the completion routine, 
either $CMPAL or $CMPCS, located in LB: [1,2] SYSLIB.OLB, as the first 
input file. Although the completion routines are located in SYSLIB 
(which is ordinarily referenced by default) , you must explicitly 
indicate it and link it as the first input file. You must also 
specify in the PAR option a base for the partition in which the 
library will reside. These two steps locate the completion routine at 
virtual of the library's virtual address space. 

You specify the name of any global symbols that you would like to 
exclude from the library's .STB file as the argument to the GBLXCL 
option. You must exclude from the .STB file of a supervisor-mode 
library any symbol defined in the library that represents the 
following: 

• An entry point to a subroutine that uses the stack to pass 
parameters 

• An entry point to a subroutine mapped in user mode that the 
referencing user task calls 

A sample TKB sequence for building a CSM library in UFD [301,55] on 
SY: follows: 

TKB>CSM/-HD/LI/PI ,CSM/MA,CSM= 

TKB>LB: [[1,2]] SYSLIB/LB:CMPAL,SY: [ [301,55] ]CSM 

TKB>/ 

Enter Options: 

TKB>STACK=0. 

TKB>PAR=GEN:0:2000 

TKB>CMPRT=$CMPCS 

TKB>GBLXCL=$SAVAL 

TKB>// 
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■ SOPERVISOR-MODE LIBRARIES (RSX-llM-PLOS ONLY) 

Tlie library is built without a header or stack, like all sharea 
regions. It is position independent and has only one program section 
•named . ABS". The /LI switch accomplishes this , eliminating program 
section name conflicts between the library and the referencing task. 

The completion routine module of SYSLIB,- CMPAL, is specified first in. 
the input line. The library will run in partition GEN at and is not 
more than IK, These are , two aspects of building supervisor -mode 
libraries specific to CSM libraries: the completion routine must be 
linked first, and must reside at. virtual 0. Why the CSM • library must 
reside at virtual is discussed, in Section 8*8.5. 

The CMPRT option specifies thei global- symbol $CMPCS, which is the 
entry point, of : the completion routine. Note that the, SYSLIB module; 
,,name is "CMPCS" and its corresponding global symbol is "$CMPCS". 

The GBLXCL option excludes $SAVAL from- the nbrary's .STB file because' 
.the user task must reference, a :CGpy of ^■$SAVAL' ;that: is -mapEied^/with:- user-, 
^mbde- APRs.'-.. .,■.■■:■■.■■,■ ■".'.' ,■ ■' ./: "/'•j: ,■■..■.■ ■ -■.■'■'' '- ' ..' ." 



^..7.2. Linking"; tp. a. CSM. Library;. ■..,■ -^ ■/■■.-■. .'■ 

If your task links to a user-owned CSM library, , you .use the REiSSbp- 
bption; ' 'If your task links to a system-owned CSM library, you. use the; 
SU PL IB option. These options tell TKB that the task will link to a. 
supervisor -mode library, ;■ -The option takes. up to three arguments:. 

• The filespec .CRESSUP option) or name (SDPLIB option) of, the 
■...;■.■ ^ ■■■■...'■. l.ibrary ■ ■ ■- .''■'-/■■'-■ .'''■-■■■' ■"■■:''■■■'' 

^ .•':.* -switch- .that,, tells -.the: . Task; .Builder .whether 'to . , use, 
system-supplied, mode-switching vectors 

• For posit ion- independent libraries, an APR that must be .APR 
so' that the library's completion routine , is mapped at virtual 

'■':■■'-'.'' ■ ,-. o.;.-^- ;■-■■ ■ ''■'■■//■■y/^■//■'■^ ',■[■■:-/'■■- k'- ■ :,■'.■-: '/'/'■'.■■:.-:. ' y--':} 

This information eriables the Task Builder to' find the .STB file, for 

the CSM library, include a 4-word., ; mode-switching vector within the- 

user task for e^ch call to a' sabrb.utine; within the library, and. 
-correctly map the library at virtual in' the library image.-; 

The following sample task-build command sequence builds a task - nam^d ; 
REF, which references the library SUPER; that you built in the previous" 
" section: . ■ . ; 

TKB>REF,REF=REF 

TKB>/ 

Enter Options: 

TKB>RESSUP=SUPER/SV:0 

TKB>// 

This sequence tells TKB to include in the logical address space of REF 
a user-owned, supervisor-mode library named SUPER. TKB will include a 
4-word mode switching vector within the user task for each call to a 
subroutine within the library. The CSM library is position 
independent and will be mapped with APR 0. 
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8.7.3 Example CSM, Library and Linking Task 

This exampLc shows you the code, maps , and TKB command sequences for 
building and linking; to a CSM- library that contains- no data in a 
system not having, user data space.. Example 8-1 shows the code for the 
library SUfKR, and Exarnplo 3-2 shows its accompanying map. Example 
8-3 shows the code foe the completion routine $CM'PCS that is linked in 
to SUPKF? fro-n SYSLTR. Kxample 3-.4 shows the code for referencing task 
TSUP, and Example 8-!5 shov/s its acco;npanying map. /• 

Exatr.ple 8-1 Code for SUPER. MAC . 



SAVE ALL :REGI'STERS 

SKIP OVER NUMBfiROF' ARGUMENTS- 

GETr ADDRESS OF LIST 

GET ADDRESS OF LENGTH OF Li ST 

GET LENGTH OF LIST 

IF NO ARGUMENTS 



copy 

COPY LENGTH OF LIST 

MOVE POINTER TO NEXT ITEM 
COMPARE ITEMS 
IF LE IN CORRECT ORDER 
SWAP ITEMS 



DECREMENT LOOP COUNT 

IF NE LOOP 

DECREMENT 

IF EQ SORT COMPLETED 

GET POINTER TO NEXT ITEM TO BE COMPARED 





.TITLE 


SUPER 




. riJKNT 


/Ol/ 


SORT: : 








CALL 


SSAVAL 




TST 


{K5) + 




MOV 


(R'i) + ,RO 




MOV 


(R5)+,R4 ; 




MOV 


!R4),R4 




BEQ ,. . 


40$ ' ■ - ; 




MOV 


R0,R5 ■ ; 




DEC 


R4. -- ■■- ., ■ ■ -^ ; 


109: 


■ ■ . ■■ ■ 






MOV . 


R5,R0 ■■; 




MOV 


R4,R3, ; 


20$: 








: TST 


(R0) + 




CMP 


{R5),(R0) ; 




BLE 


30$ 




MOV 


(R5),R2 ; 




MOV 


{R0),(R5) ; 


30$ : 


MOV 


R2,(R0) ; 




DEC 


R3 




BGE 


20$ 




DEC 


R4 ; 




BLE 


40$ 




TST 


(R5)+ ; 




BR 


10$ 



40$: 



RETURN 



SEARCH : 


J 






CALL 


$SAVAL 




CMP 


#4,(R5)+ 




ENE 


20$ 




MOV 


(R5)+,R0 




MOV 


(R5)+,R1 




MOV 


(R5)+,R2 




MOV 


fR2),R2 




BEQ 


20$ 




MOV 


(R'-OtRS 




MOV 


R2,R3; 


10$: 








CMP 


(R0),{R1)+ 




BEQ 


30$ 




BMI 


20$ ■ ■ 




DEC 


R2 ,.;: 




BNE 


lOS • 



SAVE ALL THE REGISTERS 

FOUR ARGUMENTS? , 

IF NE NO 

GET ADDRESS OF NUMBER TO LOCATE 

ADDRESS OF LIST SEARCHING 

GET ADDRESS OF LENGTH OF LIST 

GET LENGTH OF LIST 

IF NO ARGUMENTS 

ADDRESS OF RETURNED VALUE 

COPY LENGTH 

IS Tills THE NUMBER?; ■ 

IF EQ .YES 

IF m 'NUMBER NOT THERE 

DECR-EMENT LOOP COUNT 

IF HE STOT AT END OF LIST 



(continued on next page) 
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SUPERVISOR-MODE LIBRARIES (RSX-llH-PLUS ONLY) 



Example 8-1 (Cont.) Code for SUPER. MAC 



20$ : 



30$: 



MOV #-l,(R5) 

RUTORH 

SUB R2,R3 

TNC R^ 

MOV R3,(R5) 

RETURN 

.END 



; END OF LIST PASS BACK ERROR 

; NUMBER fOUND - GET INDEX INTO LIST 

r 

; RETURN INDEX 



Kxample 8-2 Memory Allocation Map for SUPER 



'SBPERvTSK;! Memory allocatior: man TKB M4fJ.I0 
"',j^i ' 29-DKC-S2 1t:(I4 



Pago 1 



Partitibti I1J^•:■ : GEN 
Td&atific:a-;ior. : 020 3 
Tas-te- tlif; : ;301 .St] 
Task attributes: -HD.PI 
Total laciiri^ss windows: 1. 
Task 'ini;;_;o aizi? : 16 0. worcJs 
"Task adcrcss limits: 000000 0004'73 
R-W; disk blk limits: 000002 000002 000001 OOOO: 
*** Rb-oi Hfimsn! : rM^Ar. 



H/W mem liiits: 000000 C00473 000474 00310. 
Disk lil"k lim-ls: 0U0Q;i2 000002 00000- 00001. 



Memory a I lor;■3^ i on synopsis: 
Section 



Tit If Tr-fiil Fill- 



HUK:. ; f UW, I , LCL , H.-;L ,C0N1 



000000 000474 oo:uo. 

000000 000136 00094. CMPAL 0203 

OOOLJfi OO.lUfi 000')4. "MHAL 0203 

000Z74 000136 00094. S-JP"R 01 

000432 000042 00034. SA7AL 00 



SYsr,in.o[.n;G 

SlfSLlB;0L3;6 

srjpRR.onj; i 

GYSr,Tn.0r,f?;6 



/Global symbols : 
SEARCH 000352-P, SORT 000274-? SCMP^L 000022-H FCMPCS fiOOllO-R SRAV^r, 000'?:i2- 



Task biii L.-i 



Stat ist icy : 



Total wor< filo roforoncns : 32';. 

Work .file ..teads :, ,0. : -.' - 

Work file writes: 0. - 

Si.ze of core pool: 6.988.- words (27. pages) 

Size of work file: 1024. words (4. pages) 

Elapsed tinie:OO:00 :04 
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sriDRRUTsriR-Mnm? t.trr&rtrs f rry-I iM-pr.ns riNr.v^ 



Example 8-3 Completion Routine, $CMPCS, from SYSLIB.OLD 



.TITLE CMPAL 
•IDENT /0204/ 



COPYRIGHT (c) 1983 BY 

DIGITAL EQUIPMENT CORPORATION, MAYNARD 

MASSACHUSETTS. ALL RIGHTS RESERVED. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED 
AND COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE 
AND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS 
SOFTWARE OR ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR 
OTHERWISE MADE AVAILABLE TO ANY, OTHER PERSON. NO TITLE. TO AND 
OWNERSHIP OF' THJE. SOFTWARE IS' 'HEREBY TRANSE'EBED . , '. 

THE INFORMATION .'in THIS DOCUMENT .IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD. NOT, BE CONSTRUED . AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OP 
ITS SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED. BY DIGITAL. 



. ENABL LC 



This module supports the "new" transfer vector format generated by 
the taskbuilder for entering super mode libraries. This format 
optimized for speed and size ant3 supports user data space tasks. 

The CSM dispatcher routine and the standard completion routines, 
$CMPAL and $CMPCS are included in this module due to the close 
interaction between them. 



**-CSM Dispatcher-Dispatch CSM entry 

This module must be linked at virtual zero in the supervisor mode 
library. It is entered via a four word transfer vector of the form: 

MOV #corapletion-routine,- (SP) 
CSM Iroutine 

Note: Immediate mode emulation of the CSM instruction is required 
in the executive. 

The CSM instruction transfers control to the address contained in 
supervisor mode virtual 10. At this point the stack is the following; 

(SP) routine address 

2(SP) PC (past end of transfer vector) 

4{SP) PS with condition codes cleared 

6 {SP) Completion-routine ajddress 

10 (SP) Return address 



(continued on next page) 
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SUPERVISOR-MODE LIBRARIES (RSX-llM-rPLUg ONLY) 



Example 8-3 (Corit.) Completion Routine, $CMPCS, from SYSLIB. OLD 

; A routine address of is special cased to support return to 
.; supervisor mode from a user mode debugging aid (ODT) . In this case 
; stack is the following: 

; (SP) zero 

; 2(SP) PC from CSM to.be discarded 

- ■ ; ■ 4(SP) PS from CSM to be discarded 

; 6(SP) Super mode PC supplied by debugger 

; , lO(SP) Super mode PS supplied by debugger 

•■' ... 

, ; To allow positioning at virtual zero, this code must be in the blank 
; PSECT which is first in' the TKBs PSECT ordering. 

'"-• .'PSECT , "■■":■■".'."■ ■■'.-■■;. : '■■■ 

-. "■„:■.. .EMABL.' LSB■■■ 
; Debugger retiirti to super mode entry. Must start at- virtual zero . 
, . .: CMP ; ■ /{SP) + , (SP)>V :•■ ; :CleanVoff ^PS :and PC from •CSM\ 

-■ :" •*i*:-.SSR'PI-SOPER,;rijdde\RTI ' . ■ ; f :■;/..'-- ,:. 

; This entry point performs the necessary stack management to allow 
- .;' an RTI' from super mode to either super mode or user mode. 
' ; The. is as : required for an RTIi - _ 



'■; . - ■ (SP); 

; ; . 2<SP) 

$SRTI : : TST 
BR . 



Super mode PC 
S.uper mode PS 



2(SP) 
70? 



; Returning to user mode? 
. ; Join common code 



; CSM transfer address, this word must be at virtual 10 in super mode 



. ;:.WORD^ CSMSVR 
: ; , D i spa fcch. CSM eh t r y .. 



■; GSM dispatcher entry 



CSMS.VR: MOV . 6 (SPJ ,2 (SP) .; Set completion routine , address for RETURN/ 
■ JM.P_, • ? @(SP)+; ■ ,-..;.- ;. Transfer -to. super mode, library routine 

■■; *i*--$CMpALTComplei:io4i routine: -which 

;• Copy 'all conditioncodes to' stacked I*S, Current stack: •.-''' 

-; ; ;(SP> PS with 'cdndtion. codes cleared , r : 

;- 2 (SP) .Completion routine address (to be discarded) 
■J- "-....■ 4(SP) ■ - Return^ address ■■ '-■ ■■ ■-.:■..■ ^ -:':'■■' "■ 



$CMPAL: :BPL 
' BNE. 
BVC 
BIS 
BR 
BIS 
BR 



10$: 



40$ 

20$ 

10? 

#16, (SP) 

$CMPCS 

#14, (SP) 

$CMPCS 



Set NZV 



Set NZ 



(continued on next page) 
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SUPERVISOR-MODE LIBRARIES 'RSX— IIM— PLUS ObJLY^ 



Example 8-3 (Cont.) Completion Routine, $CMPCS, from SYSLIB.OLD 



20$: 


BVC 


30$ 






BIS. 


#12, (SP) 


',,;set,'Nv 




BR 


$CMPCS 




30$: 


BIS 


#LO,<SP} 


••■■Bit ••.»;; 




BR 


$CHPCS 




40$: 


BtJE 


■ 60$ 






BVC 


50$ 


='."■ " ''"" ■■ ' '■■^'*■■ 




- BIS ..■. 


■■ #6,(SP) , 


'■.Set„''z^ 




BR 


$CMPCS 




50$: ; 


BIS. 


#4 , (SP).. 


•'"■Sep':zl] 




. BR 


. $CMPCS 


i. ' '■ •:■' '' \ '' 


60$: 


BVG 


.$CMPCS , 


' . '''■•■ _ ■ -. 


■\. 


. .'^BIS-j 


■ -#2,.J(SP) :,- 


■ ', ■""'■"'"• ^ '"'''"':■ 



; **-$CMPCS-Completion routine, which sets up only C in the ■ PS 

f ' ■ . ^ ' ' ' ■-.'.''.'■ 

.; Copy only carry to stacked PS.. Current stack: 

' ■ ' . . 

,; (SP) ' P,S with coridti oh codes cleared 
; ' 2(SP). Completion routine address (to be discarded) 
; 4 (SP) . Return address 



$CMPCS: 



70$: 



80$: 



:ADC (SP) ; Set up carry 

MOV 4(SP),2(SP) ,; Setup return address for RTT 

MOV (SP)+,2(SP) ; And PS. Returning to super mode? 

BPL 80$ ; If PL yes 

MOV .#6,-(SP) ; Number of bytes for (SP) , PS, and PC 

ADD SP,(SP) ; Compute clean stack value 

MTPI SP ; Set up previous stack pointer 

RTT ; Return to previous mode and caller 

•DSABL LSB 



.END 



Example 8-4 Code for TSUP.MAC 



.TITLE TSUP 

.IDENT /Ol/ 

•MCALL QIOW$,DIR$,QIOW$S 

WRITE: QIOW$ lO.WVB, 5> 1, , , ,<O0T, ,40> 

READIN: QIOW$ I0.RVB,5, 1, , , ,<0UT,5> 



I ARRAY: 


.BLKW 


12. 


LEN: 


.BLKW 


1 


I ART: 


.BLKW. 


1 


INDEX: 


.WORD 





OUT: 


.BLKW 


100. 


ARGBtK: 






EDBOF: 


.BLKW 


10. 



(continued on next page) 
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SUPERVISOR-MODE LIBRARIES (RSX-llM-PLUS ONLY) 



Example 8-4 (Cont.) Code for TSUP.MAC 



h'MTl: 


.ASCIZ 


irMT2: 


.ASCIZ 


FMT3: 


.ASCIZ 


FM'IM: 


.ASCIZ 


FMT5: 


.ASCIZ 



/S 2S ARRAY (%D;.=/ 
/%N?,2SNt)MBER TO SEARCH FOR?/ 
/%N%2S%D WAS FOUND T.V ARRAY (%r3)/ 
/%N%2S%1-) WAS NOT IN ARRAy/ 
/'i2SARRAY(1iD)=%D/ 



. avfiN 



START: 



55 



10$: 



20S: 



MOV 


#IAHRAY,RO 


MOV 


#10, Ri 


CLR 


(RO) ! 


DKC 


Rl 


BNE 


65 


MOV 


*IARRAY,RO 


MOV 


#INL5EX,R2 


MOV 


ifFMTl,Rl 


MOV 


(R2) ,:-;[)Bl.'F 


iNC 


EDBJF 


CALL 


PRIST 


CALL 


READ 


MOV 


lART, (R0)+ 


BEQ 


20$ 


INC 


;R2) 


CMP 


(S2),#10. 


DNE 


10$ 


MOV 


(R2) ,LEX 


MOV 


#argbl:<,r5 


MOV 


42,(R5)+ 


MOV 


41 ARRAY, (R5) 4- 


MOV 


*r.KM, (R5! 


MOV 


#ARGBLK,R5 


CALL 


SOR'I' 



; + 

;Task Builder 
;contRx- swit 
; tho vector 
;continaes ex 



GKT ADDRESS OF ARRAY 
SET LEMGTM OF ARRAY 



• r M T Ti I A r 

; LOOP 



n ij n Y 



replaced call to 
ching vector. Flow 
iid back via thL- co: 
cuting at r.':i« n«xt 



FORMAT SPKCIFICATION (ADDRilSS 
OF INPUT STRING) 
GET IND-;X 

PRINT MESSAGE 

READ INPUT 

PUT BINARY KEYBOARD INPUT INTO ARRAY 

ZERO MA.^KS END OF INPUT 



:f ns yes 

calculate length of array 
get address of argument block 

NUMU-;r OF AKGUMKNTS 
PUT ADD li ESS OF ARRAY 



SORT AR-<AY 

SORT siibroiit. ine in SUPl.T!* with 4-word 
oF control swi tclics to SUPLIB via 

mploLion couLint? $CM?CS. TSL'P 
i nstruct i on . 



30S: 



CLR R2 

MOV #IARRAY,RO 

INC R2 

MOV R2,RDBCF 

MOV (RO) + ,ED15UF+2 

MOV #FMTr5,Rl 

CALL PHINT 

CMP R2,LEN 

ULT 30$ 

MOV J1FMT2,RI 



gv;t array ad;);jess 

in'crement index 
g.-:t :nd:-'x for print 

get CONTESTS OF ARRAY 

GET ADDRESS OF FORMAT SPEC IF ] CAT TON' 

KOS;: TO PRIST? 

IF r.E Y"S 

G';T A15D.-iESS OF FOHMAT SPCCI FICATION 



(continued on nnxt. page) 
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Example 3-4 (Cont . ) Code for TSOP.MAC 



CALL 


PRINT 


CALL 


READ 


MOV 


#ARGBLK,R5 


MOV 


#4,«R5)+ 


MOV 


#-IART, (R5} + 


MOV 


f IARRAY,(R5)+ 


MOV 


#LEN,(RS)+ 


MOV 


♦INDEX, (RS) 


MOV 


#ARGBLK,R5 


CALL 


SEARCH 



OUTPUT MESSAGE 
READ RESPOKSE 

SET NUMBER OF ARGUMENTS 

SET ADDRESS OF NUMBER LOOKING FOR 

SET ADDRESS OP ARRAY 

SET ADDRESS OF LEN OF ARRAY 

ADDRESS OF RESULT 

SEARCH FOR NUMBER IN- I ART- 



;Call to SUPLIB for SEARCH subroutine. 



40S: 



lOOS: 



TST • 


,, INDEX" 


BLT 


40$ 


MOV 


"IART,EDBUF 


MOV, 


INDEX, EDBOF+2 


MOV 


-#EMT3,R1 ■ 


CALL 


• PRINT 


BR 


- 100$ 


MOV 


#FMT4,R1 


MOV 


IAST,EDBUP 


CALL 


PRINT 



CALL 



$EXST 



WAS NUMBER F.OUND? , 

IF LT NO ■ 

GET NUMBER LOOKING FOR 

GET ARRAY NUMBER 

GET FORMAT ADDRESS 

DONE 

GET FORMAT ADDRESS 
GET NUMBER 



. ; EXIT WITH STATUS 



PRINT: 








CALL 


$SAVAL ; 




' MOV 


#OUT,R0' . ; 




MOV 


#EDBUF,R2 ; 




CALL 


$EDMSG ; 




MOV 


R1,WRITE+Q, IOPL+2 




■ DIR$ 


♦WRITE 




RETURN 





SAVE ALL REGISTERS 

ADDRESS OF OUTPUT BLOCK 

START ADDRESS OF ARGUMENT BLOCK 

FORMAT MESSAGE 

; PUT LENGTH' OF OUTI>UT 

BLOCK INTO PARAMETER BLOCK 

WRITE output! block 



READ: 



CALL 


$SAVAL 


DIR$ 


4R£ADIN 


MOV 


#OUT,R0 


CALL 


$CDTB 


MOV 


R 1,1 ART 


RI^UKH 





; SAVE ALL REGISTERS 
READ REQUEST ' I 

GET KEYBOARD INPUT 

; CONVERT KEYBiOARD INPUT TO BINARY 

; EOT INPUT JljlTO BUFFER 



.END 



START 
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Identa^Eiip'lit'iJin ; f ■■■ai'''' •!.,.;>• v.,,^'--,., "■■;•' ,,,^' ••-.., ,;^' •^-.r^--,,. ■'""■■ 'T'? '"-'':-<.'" ■■■■-.'"' ■"-•," :•■=.».; '■•■■■ .,•"■■•",<,'■■.••'«.. " ■-^t-...,- • 

Ta s te.r- -iBager-'-^IW^C'-'J-vl^^i ?'^^^^^ 

Taskf-vaaaifess i^ife|l<pOlQ|W. 90S|3a.>sr> 

R-W i«isfc.;|i4;':M«|i'%^|^.Ct^4|»-,|0ft0^ 00005 . 

* * * ;|l&a|;*s^|[ii^ti:lS'T?ati;^ <' ;<;; ?;!;;;: -'Cii il;*;;?'..! 

R/w i;ijfemr-'5ifeE^5)tf^ o3s;i5lr5Q5Hi-**52 652. 

puR§& 3' •c:kov''I'*:!:^C're£/g<|n).^; ■■■"■-,; oa3'6'3tff'0,d'pOTi-'-Qft 06^ ,;■■•>::■••> -I ■"•'-C:"-- .;'■• -.r':-- 7 



■•fStlP "prompts'-' you' to'"-eat.ex •>■^numBepS■ >'at"''^:"yo«r''"'tismi^ ';'■* ••&■ .;.";ica'il;s'': •.a" 

"subroutine''' in ■■■■SUPER ;t,oV ■■■■sort/, tke '-nWb^rsV'-'^ 

'you; entered as artay entries and prompts y to regdest a number to 

search /for. TSOP calls > sabroutin& in ./S to: search for the 

/nuinbe'r/. / Finally,: .TSiUP indicates at youj: /tei:min.al / either ,.; that," the 

number was not found or the array location in which the number is 
1 stored . 
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SUPERVISOR-MODE LIBRARIES (RSX-llM-PLUS ONLY) 

8.7.3.1 Building SOPER— To build SUPER in UFD [301,55] on SY:, use 
the following task-build command sequence: 

TKB>SUPER/-HD/I,I/PI,SOPER/MA,SUPER= 
: TKB>LB: [tl,2]]SYSLIB/LB:CMPAL,SY: [ {301 , 55] ] SUPER 
TKB>/ . 

Enter Options: 
■^ ; ; T.KB>STACK=0 ■ : 

■■;:.TKB>PAR=GEN: 0:2000 : • 

' :• TKB>CMPRT=$CMPCS . 

.; ;TKB>dBLXCL=$SAVAL ' 
■■:•'''■, T;KB>// -■ ■ . . 

SUPER is build withput a header or : stack. It is position independent 
and :tias.. pnTy one. program sectipn, named .BLK. The /LI switch 
aceoinplisheS:' this-, eliminating program section name conflicts between 
the library and the referencing .task. 

:The -completion." roatine module of SYSLIB, CMPAL, is specified first in 
rtbe.\input line. .The library wilL run in partition GEN at and is not 
more than IK. 



'The GBLXCL option excludes $SAVAL- from the library's .STB file. You 
exclude $SAVAL from the .STB file because the referencing task, TSUP, 
:;also calls $SAVAL. If TSUP finds $SAVAL in the .STB file of SUPER, it 
will not link a separate copy of $SAVAL into its task image from 
SYSLIB. If TSUP cannot link to a copy of $SAVAL that is mapped 
through user APRs, the TSUP would call $SAVAL as a subroutine residing 
within the supervisor-mode library, but without the necessary 
mode-switching vector and completion routine support. This option 
forces TKB to link $SAVAL from SYSLIB into the task image for TSUP. 

The memory allocation map in Example 8-2 shows the following: 



• SUPER begins at virtual 0. 

• The completion routine, $CMPAL, is 
from SYSLIB at virtual 0. 



linked into the library 



• The entry point $CMPAL is located at virtual 22, SEARCH is 
located at 35, and sort is located at 274. All of these entry 
points are relocatable. 



8.7.3-. 2 Building TSUP - Use the following task-build command sequence 
to build a task, TSUP, that links to SUPER: 

TKB>TSUP,TSUP=TSUP 
TKB>/ 

TKB>RESSUP=SUPER/SV:0 
. TKB>// , 

This command sequence tells TKB to include in the logical address 
space of TSUP a user-owned, supervisor-mode library named SUPER. TKB 
includes a 4-word, mode-switching vector within the task image for 
each call to a subroutine within the library. The library is position 
independent and is mapped with supervisor T-space AP'RO. This is a 
-reguirementf for . CSM libraries because the CSM expects to find the 
entry point of the completion' routine at location 10. 
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SUPERVISOR-MODE tlBRARI ES . ( RSX-r 1 IM- PLCS ONLY ) 

The memory allocation msip for TSUiP (Example 8-5)/ shows : 

• §CMPAL is linked from the .STB file of theilibrary and begins 
at location 0. 

• The mode-switching vectors begin at 005136 and arc 16. bytes. 
That means that TSUP calls subroutines within tho library 2 
times (4 words per vector). 

• The initiation routine gSOPL is" located at 4700. 

• The SEARCH and , SORT siibroutines that were Located at virtual 
112 and 32, - respectively, iri the virtual .address space of 
SUPER have been .relocated ' to/ 'the mbderswi tching vectors 
residing' at 5136. and Vsife/respeGtively, 'in ;TSDP. 

• The SAVAL" .module from SXStliBcdnta in has been linked 
into the- tafek.,i'mage*^ in stead.:/. of ^^^^^^^ $SAVAL from the 
library's. ...STB:' tile. V.7 ■ ■•/ :",\\'s^- ■J-'r/.'J /.''^''^ 



8.7.3.3 Running TSDP - After building SUiPER and TpoP as indicated in 
the task-build conirha/nd' sequence- (JiscUssed py you install 

SUPER and run TSUP. TSUP prompts, you ,'f or. /a hutnber : ;' ' 

■' AB:RAY (x). .■■■■■,' ■.'''■■'.""/: -^ -"■-'':;■■:''' ^ ^'' ' \'. 



The position in which, to store; the.' number in the array. You 
enter a number. . TSUP Stores the ; number in the array and 
prompts you again for a : . nunibej;.. This; cprt.binuos until you 
either have entered' a 0, an .illegal number, or 10 numbers. 
Then TSUP calls the SORT routine in' SUJ»ER.. .r 

You enter a number. TSUP calls the SEARCH rodtine /in SUPER. Then 
TSUP outputs a message indicating y*hetherth,&-.-nu,mt>er.. was in the array. 



8.7.4 The CSM Library Dispatching Process / /:;/ 

When you build the referencing ,ta-sK;/ if you/" spe'c^^ SV argument to 
the RESSUP or SUPLiB/,dption;r: /..then- ..//TKB/ includes a 4-word 
context-switching vector for each call /to a subroutine in the library. 
This has been very generally discussed in Sbction 8. 2. This section 
discusses the CSM library vector in detail i ■ 

CSM mode switching occurs as follows: • 

1. The vector is entered with the return address/ on top of the 
stack (TOS) . ■/ 

2. The vector pushes the completion routine address on the 
stack. 

3. A CSM instruction is executed with the supervisor-mode, entry 

instruction : 

a. Evaluates the source parameter and stores the entry point 
address in a temporary register 
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b. Copies the user stack pointer to the supervisor stack 
pointer 

c. Places the current PS and PC oh the, supervisor stack 
clearing the condition codes in the PS 

d. Pushes the entry point address on the .supervisor stack 

e. Places the contents of location 10 in supervisor I-space 
into the' PC ' .. "■ 

The stack looks like this when the processor begins to execute at the 
contents of virtual 10 in supervisor mode: 



user sp ■ r-> 



return address - 

completion routine address' 

V'ps .. 
.'.:-.' . PC 



super sp — ; — > entry point address 

The most important aspect of how the CSM .library mode-switching vector 
works in that the processor begins executing at the contents of 
'virtual 10 in supervisor mode. This is why the completion routine- 
must be located at virtual 0, so that virtual location 10 is within 
the completion routine. 



8.8 CONVERTING SCAL LIBRARIES TO CSM LIBRARIES 

You can easily convert your SCAL libraries to CSM libraries. 
Rebuilding a task on an RSX-llM-PLUS V2.0 system or later that linked 
to a library on a VI. system requires that you rebuild the library 
also. Rebuild the library specifying the completion routine as the 
first input module. If the library was not built to run at a starting 
address of in its partition, rebuild it so that it does begin at 
to enable TKB to find the completion routine. 



8.9 USING SOPERVISOR-MODE LIBRARIES AS RESIDENT LIBRARIES 

Supervisor-mode libraries can double as conventional resident 
libraries. For position-independent, supervisor-mode libraries, you 
rebuild the referencing task using the RESLIB option instead of the 
RESSUP option. Indicate the first available user-mode APR that you 
want to map the library. For CSM libraries this will always change, 
because you cannot map a shared region with APR 0. You do not have to 
rebuild the library. 

For absolute supervisor -mode libraries, rebuild the referencing task 
using the RESLIB option instead of the RESSUP option. Rebuild the 
library only if the beginning partition address in the PAR option is 
incompatible with the address limits of your referencing task. . 



8.10 MULTIPLE SOPERVISOR-MODE LIBRARIES 

A user task can reference multiple supervisor-mode CSM libraries. 
However, : all the CSM libraries must use the completion routine tha:t 
begins at virtual zero in supervisor-mode instruction space. 
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8.11 LINKING A RESIDENT LIBRARY TO A SUPERVISOR-MODE LIBRARY 

You can link a conventional resident library to a supervisor-mode 
library using the following command sequence: 

TKB>F4PRES/-HD , F4PRES , F4PRES , LB : [ [ 1 , 1 ] ] F4PRES= 

TKB>F4PRES/LB 

TKB>/ 

Enter Options: 

TKB>STACK=0 

TKB>SUPLIB=FCSFSL:SV 

TKB>PAR=F4PRES: 140000: 20000 

TKB>// 

This command sequence shows you how to link F4PRES to FCSFSL. 



8.12 LINKING SUPERVISOR-NODE LIBRARIES 

You cannot link supervisor-mode libraries together, and you cannot 
link a supervisor-mode library to a resident user-mode library. 
Calling a user-mode library is not possible because its code is not 
mapped through the I-space APRs while in the supervisor-mode library. 
However, you can link user-mode libraries to a supervisor-mode 
library. 



8.13 WRITING YOUR OWN VECTORS AND COMPLETION ROUTINES 

You can write your own mode-switching vectors and completion routines. 
This may be necessary for threaded code. If you use your own vectors, 
build them into the task and use the -SV switch on the RESSUP or 
RESLIB option when you build the referencing task. If you create your 
own completion routines, write your completion routine to resemble the 
system-supplied completion routines (see Example 8-3) as much as 
possible. If you do not retain the last three lines of code as 
indicated in Example 8-3, then if the Executive processes an interrupt 
before the mode switch back to user mode has completed, your task may 
crash. 



8.14 OVERLAID SUPERVISOR-MODE LIBRARIES 

It is possible to use overlaid supervisor-mode libraries. Three 
restrictions must be noted when building these libraries: 

• The completion routine for the library must be in the rboti. ' ■■ 

• Only one level of overlay is allowed. This is illustrated in; 
Figure 8-4. ' r - 

• Although the Fast Task Builder (FTB) can link ■ to 
supervisor-mode libraries, it cannot link to overlaid 
supervisor-mode libraries. 
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A 



ROOT 
ALLOWED 



ROOT 

ALLOWED 



ROOT 

NOT ALLOWED 



^< ■1^.■•-^.• 



Figure 8-4 Overlay ConflguratiQTiAl Vowed Eor 
Super V i sor--Mode L I br a r i es 
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CHAPTER 9 
MOLTIDSER TASKS 



9.1 INTRODDpTIQiSr . 

A multiusec -t^sk is.'a task, that ,shares/the pure (read-only) portion of 
its code wi,th."ty?o or more copies of the impure (read/write) portion of 
its code. Wh^ri the systeni receives an initial run request for - a 
multiuser _t'ask, ' .a- copy' of' both- the read-only and read/write portions 
of the task are, read -into physical , memory. As long as the " task is 
running, ail subsequent run requests for it result in the system 
duplicating only- the xead/write- portion of the task in physical 
memory. Thus,' multiuser tasks are memory efficient. 

When you build a task, you designate if as multiuser by . applying the 
/Ml) switch. , to the, :task -image file,' This switch directs, the Task 
Builder to create two regions for the task. One region (region 0) 
contains the read-write portion of the task; the other region (region 
1) contains. the read-only portion of the. task. 

As with al I other, tasks, ,TKB uses a program section's access code to 
determine its placement within a multiuser task's image. It divides 
address space into read/write and read-only, sections. Unlike in a 
single user task,/ however , the read-only portion of the task is 
hardware protected, /In addition, TKB separates the read/write 
portions of; ,3 multiuser .task from the read^-only portions and places 
them in separate .■regions at .opposite; ends of the task's address space. 
It allocates the- 'low-address APRS to the read /write portion (which 
includes the 'task ' s header and stack area) and the highest available 
APRS to .the read-only portion. Figure 9-1 illustrates this 
allocation. ■';. / ' ; . 

For I- and 'B-space multiuser tasks, in addition to having the 
multiuser task divided into regions of read-only PSECTs and read/write 
PSKCTs, theise regions themselves are divided into I-space areas and 
D-space areas. All of the following combinations must be present in 
an I- and D-space multiuser task: 

• .PSECT psectna,mew, RO, I, ... 

• .PSECT psectnamex, RW, I, ... 

• .PSECT psectnamey, RO, D, ... 

• .PSECT psectnaraez, RW, D, ... 

*— *'-^-* *-*"-*- ^'.v- ...^^^ ^i.,^j ».^^ w.^w ^ ^a^^ ,, WW £-«*.. 1 -a 

contains memory-resident overlays, TKB allocates two window blocks in 
the header of the task. When the task is installed, the INSTALL 
processor will initialize these window blocks as follows: 

• Window block describes the range of virtual addresses (the 
window) for the read/write portion of the task. This region 
always contains the task's header. 
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• Window block 1 describes the range of virtual addresses for 
the read-only portion. 

Figure 9-2 below shows the window-to-region relationship of a 
multiuser task. . 



APR 7 — 
APR6 — 
APR 5 — 
APR 4 — 
APR 3 — 

APR 2 — 
APR 1 — 

APR — 



UNUSED 



READ-ONLY 
PROGRAM 
SECTIONS 



iUNUSED: 



READ/WRITE 
PROGRAM 
SECTIONS 



HEADER & STACK 



ZK-441-31 



Figure 9-1 Allocation of Program Sect iort^ a Muiiiuser Task 



9.1.1 Overlaid Multiuser Task 

If a multiuser task is an overlaid task (described in Chapter 3), the 
read-only portion of the task can be made up of the following: 

• The read-only program sections of the root segment 

• Branches of an overlay structure if the complete branch is 
memory resident and read-only 

• A co-tree structure if the entire co-tree is memory resident 
and read-only. 



9.1.2 Disk Image of a Multiuser Task 

The disk image of a multiuser task is somewhat, different from that of 
a single-user task. The read-only portion of the task is placed at 

thA #»Tld Ct^ i-hei d>^V ilT^aa^ Th^a toT a^-1 -s/o KIo'^T^ nnmK^aT- -f\P ^h^' ■•-/a =1 ^ .„ ri*-« 1 ^' 

portion and the number of blocks it occupies appears in the label 
block. The read-only portion of the image is described in the first 
library descriptor of the LIBRARY REQaEST section of: the label block, 
(Refer to Appendix B for more information on the task image data 
structures.); 
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HIGHEST VIRTUAL 
ADDRESS 



WINDOW BLOCK 
1 



WINDOW BLOCK 




LOWEST VIRTUAL 
ADDRESS 




REGION 1 



REGION 



T'iqure 9-2 Wint3ows Tor a Multiuser Task 



9.1.3 I- and D-Space Multiuser Tasks' 

The APR and window block assignment in an I-. and D-space 
task differs frpiti, that in a conventional multiuser task.- , 



multiuser 



D-space APRS map the; read-write; and' read-only PSECTs . that have the 
data attribute. Similarly, I-space APRs map the read-write and 
read-only PSECTs that have the instruction attribute. Figure 9-3 
shows the APR mapping for both kinds of PSECTs in an I- and D-space 
multiuser task. 

TKB needs four window blocks to map ah I- and D-space multiuser task. 
Window blocks and 1 map region 0.- which contains the read-write 
instruction and data PSECTs. Window blocks 2 and 3 map region 1, 

which contains the read-only instruction and data PSECTs. Figure 9-4 
illustrates the mapping and assignment of these window blocks for an 
I- and D-space multiuser task. 
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DATA APRS 



INSTRUCTION APRS 



DAPR7 



DAPR6 



DAPR5 



DAPR4 — 



DAPR3 — 



DAPR2 — 



DAPR1 — 



DAPRO 



UNUSED 



READ-ONLY DATA 
PROGRAM SECTIONS 



UNUSED 



READ-WRITE DATA 
PROGRAM SECTIONS 



HEADER + STACK 



IAPR7 — 



IAPR6 



IAPR5 



IAPR4 — 



IAPR3 — 



IAPR2 — 



IAPR1 — 



lAPRO 



UNUSED 



READ-ONLY 

INSTRUCTION 

PROGRAM SECTIONS 



UNUSED 



READ-WRITE 

INSTRUCTION 

PROGRAM SECTIONS 



UNUSED HEADER 



Figure 9-3 Example Allocation of Program Sections in an ,1- =arid = 

and D-Space Multiuser Task ' 
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PHYSICAL 
MEMORY 



TASK 
WINDOW BLOCKS 



WINDOW BLOCK 3 



WINDOW BLOCK 2 



WINDOW BLOCK 1 



WINDOW BLOCK 




READ-ONLY D 



READ-ONLY I 



READ-WRITE D 



READ-WRITE I 



REGION 1 



REGION 



Figure 9-4 Windows for an I- and D-Spacfi Multiuser Task 



9.2 EXAMPLE 9-1: BUILDING A MULTIUSER TASK 

The text in this section and the figures associated with it illustrate 
the development of a multiuser task. This example was created by 
concatenating into a sing]e file the resident library file (LIB. MAC) 
and the task that links to it (MAIN. MAC) from Example 5-3. It is not 
intended to represent a typical multiuser task application. However, 
it does illustrate the Task Builder's allocation of program sections 
in a multiuser task and that is its primary value. The concatenated 
source file, named ROTASK.MAC, for this example is shown in Example 
9-1. 
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Mnr.TTnesRO TieK-t; 



Example 9-1', Part 1 /Source Listing for ROTASK.MAC 





.TITLE 


' ROTASK ■ 




.IDENT 


/Ol/ 




.MCALL 


QIOW$S,RXTT$S 


OPl: 


.WORD 


1 


0P2: 


.WORD 


1 


ANS: 


.BLKW 


1 


OUT: 


.SLKW 


100. 


FORMAT : 


.ASCIZ 
.EVEN 


/THE ANSWER = 


START: 








MOV 


#ANS,-(SP) 




MOV 


#0P2,-(SP) 




MOV 


#0P1,-(SP) 




MOV 


#3 ,-(SP) 




MOV 


SP,R5 




CALL 


AADD 


" - ■■-..■■ 


CALL 


.PKIKT . 




. MOV . 


-SP,R5 / ■■ 




CALL 


■ SOBfi: 




CALL 


PRINT 


■ 


MOV 


SP,R5 




CALL 


MULL 




CALL 


PRINT 




MOV 


SP,R5 




CALL 


DIW 




CALL 


PRINT 




EXIT$S 





JO,/ 



OPERAND 1 , , ' 
OPERAND 2 
RESULT 

FORMAT MESSAGE' 



TO CONTAIN/'RESDLT / - . ■ , 
OPERAND '2 : ' ■-.',; < V" 
OPERAND £. J; ' /'. •'■■'/ 
PASSING ;3 ARGUMENTS - ' 
ADDRRSS OF ARGUMENT BLOCK' 
ADD TWO OPERANDS ' ' 
PRINT RESULTS .. . / 
ADDRESS OF ARGUMENT BLOCK 
SUBTRACT SUBROUTINE - 
PRINT RESULT'S 
ADDRESS OF ARGUMENT BLOCK 
MULTIPLY SUBROUTINE 
PRINT RESULTS 
ADDRESS OF ARGUMENT BLOCK 
DIVIDE SUBROUTINE 
PRINT RESULTS 



;** PRINT - PRINT RESULT OF OPERATION. 

f 

PRINT: MOV #OUT,R0 ; ADDRESS OF SCRATCH AREA 

MOV , #F0RMAT,R1 ; FORMAT SPECIFICATION 

MOV #ANS,R2 ; ARGUMENT TO CONVERT 

CALL $EDMSG ; FORMAT MESSAGE 

QIOW$S #IO.WVB,#5,#1,,,,<#OUT,R1,#40> 
RETURN ; RETURN FROM SUBROUTINE 

;** FORTRAN CALLABLE SUBROUTINE TO ADD TWO INTEGERS 
.PSEGT AADD,RQ,I,GBL,REL,CON 



AADD: 



CALL 


$SftVAL 




SAVE R0-R5 


MOV 


@2(R5) ,R0 




FlkST OPERAND 


MOV 


(a4(R5),Rl 


'' 'J< 


SEGONP OPERAND ■• ■ ■ . 


ADD 


R0,R1 




SUM THEM 


MOV . 


R1,@6(R5) : 


".')■ i': 


STORE RESULT 


RETURN 




•.•^■/.■l'. 


SESf ORE REGISTERS AND RETURN 



(ccfntintaed on next page) 
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CALL 


$SAVaL 


MOV 


02(R5) ,R0 


MOV 


94(R5) ,R1 


SUH 


R1,R0 


MOV 


R0,96{R5) 



, MDLTIOSER TASKS, ' ; ■ 

Example 9-1, Part 1. Source iisting .f or.\BOTASK.MAC 

;** FORTRAN CALLABLE SUBROOTINE TO SOBTRACT TWO ISTEGHRS 

.PSECT SUBB,RO,.I,GBL,REL,CON 
SUBB:: CALL $SAVAL ; SAVE R0--R5 

:; FIRST operand; 
. ■; SECOND OPERAND ' 
; SUBTRACT SECOND .FROM FIRST 
; STORE RESULT- r' ' ; " 
RETURN ;; .RESTORE REGISTERS AND RF.TURN 

;** FORTRAN CALLABLE SUBROUTINE ;tO DIVIDE WO 'INTEGERS 

.PSECT DIVV,HO,i,GBLfREL,GON .,-../;./-; .,; 
DIVV:: CALL SSAVAL , /; :■'',;-. SAVE REGS' ,R 

: 'i FIRST OPERAND .'..V 
/■^■' \r> .SECOND .OPERAND'; 
:;'■:"-;■' LOW ORDER' 16^^ &tTS 

■•■"'/.} Idivide' .■;.;■■-/ ".■":.:■/,■•■■■■ ■ 
'■-7, ■•.',;.:-. STORE :r-esult:; ■/"■:■.■:; 

.' ,';; 'REST0iREVRE,G1STER^ AND RETURN 
;** FORTRAN CALLABLE SU^^ROU'TlNE TO; MUCTI^ 

. PSECT MULL , RO; I iJdBL^j^BEL , CON ; • -' V " .' : '•; 
MULL: 



CALL 


SSAVAL , 


MOV 


@2(R5),R3 


MOV 


@4(R5) ,gl 


CLR 


R2 'f 


DIV 


R1,R2 V- 


MOV 


R2,(a6(R5>; 


RETURN 





CALL 


$SAVAL ;•:;/,•' 


"'■• ';"'"'>' 


SAVE- ROi^RS ?-;'';/;/: 


MOV 


|32(R5) ,R0 


"■"^r"'}" 


FIRST OPERAND " / 


MOV 


34 (R5) ,R1/ ■ : 


."'"" '"i ^^''■ 


^^ECO-MD OPERAND;.", ■ 


MUL 


R0,R1 : 


■ ':'y-r^^^ 't ' 


.MJULTIPLY / • .■ . 


MOV 


R1,36(R5) 


'''■-■■■ ' "■ '' ■/-!!! 


STORE RESULT 


RETURN 


'■;./ ' ' ' 


■"''" ""i=!.- /'■''*'■'" 


RESTIORE RBGISTBRS' AND RETURN 


.END 


START 







Once you have assembled ROTASK/ you can buiid it 'Witti^ following 
command sequence: '• '■-,• .-..■■ 

TKB>ROTASK/MU , ROTAS K/-WIj^^SP=ROTASK - r- ■ / ,' 

TKB>/ .-':',VV'" '"'.'.'■',■''/::- /■■ .:-■ 7; :*.■'.'■;■ -J'.V: 

Enter Options: ;-..''.' //.. - ,■ -.1 ■ '■' ■V''^, 

TKB>ROPAR=RDONLY ■ //,' 'Vl ^ ^' '.V • ,;/;■": ■/'/.;' '7 

TKB>// 7V", ,.' :■'•, 7. / -7' 7' '■.'-[ \ .■7_,''7;;;- " ''f'/J. 

This command sequence directs' TKB- .to •• build* . a jmalttii^^^ C/MU) task 

image named ROTASK.TSK and ' to 7 c^^ea-t^^^^^^ '^^P file 

named ROTASK.MAP. Because /-SP is attached to the'map 7f'il e , TKB does 
not output a map to the J i ne pointer . 

The ROPAR option specifies that the system is to load . the; read-fonly, 
portion of the task into a partition named RDONLY;, Specifyiing ' a;, 
separate partition for the task's read-only iregibn is hot a system; 
requirement. .The system will load the read/write portion into' 
partition GENi The system will not load either region until it 
receives a run request for the task. 

The map that results from this command sequence is shown in Example 
9-1, Part '2 J Note that TKB has added one field to the task attributes 
section of this map describing the disk block limits of the read-only 
portion of the task. It has also added a field to the root segment 
portion of the map that describes the memory limits of the read-only 
portion of the task. 

Finally, note that TKB has allocated space for all the program 
sections with the .read-only attribute, beginning with the highest 
available APR (in this case, APR 7). 
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Example 9-1, Part 2 Task Builder Map for ROTASK.TSK 



R0TASK,TSK;1 



Memory allocation map TKB M40. 10 
lO-DEC-82 14:42 



PAGE 1 



GEN 

01 

[7,62] 

000274 001273 OOlQOO 00512. 

001634 

MD 



Partition name : 

Identification : 

Task aiC ; 

Stack . Limits : 

PRG xfr address: 

Task attributes! 

Total address windows: 2. 

Task image size : 1088. words ■ 

Task' address limits: 000000 :004157; 

R-W^disk blk limits: 000002 000006! 000005 00005:'. 

R-0 disk blk limits: 000007 OOOOOT 000001 00001. 

*** Root segment: ROTAS K : -^ 



R/W mem limits: 000000 004157 0,04160 02160. 
R-0 mem limits: 160000 160377 000*400 00256, 
Disk blk limits: 000002 000006 000.005 00005. 



Memory allocation synopsis: 
Section 



Title Tdent File 



. BLK. : (RW,I,LCL,REL,CON) 001274 002662 01458. 

001274 000530 00344. ROTASK 01 R0TASK.0BJ;1 

AADD : (RO,I,LCL,REL,CON) 160000 000024 00020. 

160000 000024 00020. ROTASK 01 ROTASK. 0BJ;1 

DDIV : (RO,I,LCL,REL,CON) 160024 000026 00022. 

160024 000026 00022. ROTASK 01 ROTASK. 0BJ;1 

MHUL : (RO,I,LCL,REL,CON) 160052 000024 00020. 

160052 000024 00020. ROTASK 01 ROTASK. 0BJ;1 

SSUB : (RO,I,LCL,REL,CON) 160076 000024 00020. 

160076 000024 00020. ROTASK 01 ROTASK. 0Bv7; 1 

$$RESL: (R0,I,LCL,REL,C0N) 160122 000212 00138. 

Global symbols: 

AADD 160000-R DIVV 160024-R MOLL 160052-R SUBB 160076-R 



*** Task builder statistics: 

Total work file references: 2145. 

Work file reads: 0. 

Work file writes: 0. 

Size of core pool: 7086, /words (27, 

Size of work file: 1024. words (4, 

Elapsed time:00:00:07 



PAGES) 
PAGES) 
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CHAPTER 10 
SWITCHES 



You use switches and options to control the construction of your task 
image. This chapter provides detailed reference information on all 
the TKB switches. Chapter 11 describes the TKB options. 



10.1 SWITCHES 

The syntax for a file specification, as given in Chapter 1, is: 

dev: [group, member] filename. type;version/swl/sw2. . ./swn 

Optionally, you can conclude a file specification with one or more 
switches (swl,sw2, . . .swn) . When you do not specify a switch, the Task 
Builder establishes a default setting for it. 

You designate a switch by a 2- to 4-character code preceded by a 
slash {/) . If you precede the 2- to 4-character code with a minus 
sign (-) or the letters NO, TKB negates the function of the two 
characters. For example, TKB recognizes the following settings for 
the switch CP (checkpointable) : 

/CP The task is checkpointable. 
/-CP The task is not checkpointable. 
/NOCP The task is not checkpointable. 

In some cases, two particular switches cannot both be used in a file 
specification. When such a conflict occurs, TKB selects the 
overriding switch according to the following table: 

Switch Switch Overriding Switch 

/AC (Ancillary /PR (Privileged) /AC 

Control Processor) 

/EA (Extended /FP (Floating /FP 

Arithmetic Element) Point Processor) 

/CC (Concatenated /LB (Library file) /LB 
object file) 

For example: 

MCR>TKB IMG5=IN6,IN5/LB/CC 

TKB assumes that the input file INS is a library file. It searches 

task image all of the modules in INS. 
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The switches that TKB recognizes are given in alphabetical order in 
Table 10-1. Sections 10.1.1 through 10.1.30 give detailed 
descriptions of each switch, in alphabetical order, including: 

• The switch format 

• The file(s) to which the switch can be applied 

• A description of the effect of the switch on the Task Builder 

• The default assumption made if the switch is not present 



Table 10-1 
Task Builder Switches 



Format 



Meaning 



Applies 
to Pile 



Default 



/AC[:n] Task is an ancillary control pro- 
cessor . 

/AL Task can be checkpointed to space 
allocated in the task image file. 

/CC Input file consists of concatenated 
object modules. 

/CM Memory-resident overlays are aligned 
on 256-word physical boundaries. 

/CO Causes TKB to build a 
shared common. 

/CP Task is checkpointable. 

/CR A global cross-reference listing 

is appended to the memory allocation 
file. 

/DA Task contains a debugging aid. 



/DL Specified library file is a re- 
placement for the system object 
module library. 

/EA Task uses extended arithmetic 
element. 

/EL Specifies library size according 
to partition size. 

/FP Task uses the Floating Point 
Processor. 



TSK 


/-AC 


TSK 


/-AL 


OBJ 


/QC. 


TSK 


/-CM 


TSK 


/CO 


STB 




TSK 


/-CP 


MAP 


/-CR 



.TSK, 
.OBJ 

.OLB 



.TSK 



,TSK 



/-DA 
/-DL 

/-EA 
/-EL 



.TSK /-FP on RSX-llM 

/FP on RSX-llM-PLUS 

(continued on next page) 
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Table 10-1 (Cont.) 
Task Builder Switches 



Applies 
Format Meaning to File Default 



/FU All co-tree overlay segments are .TSK /-FU 

searched for matching definition or 
reference when modules from the de- 
fault object module library are 
being processed. 

/HD Task image includes a header. .TSK, /HD 

.STB 



l/ID % :: .Task, will' use; I--,: and D-space. 



TSK 



/IP Allows TKB to inform INS that the .TSK /-IP 

task purposely overmaps the 
I/O page. 

/LB Input file is a library file. 

/LI Informs TKB to build a 
shared library, 

/MA Map file includes information 
from the file. 

/MM System on which the task is to 
run has memory management. 

/MP Input file contains an overlay 
description . 

/MU Task is a multiuser task. 

/NM Tells TKB to inhibit two 
diagnostic messages. 

/PI Task is position independent. 

/PM Postmortem Dump is requested. 

/PR[:n] Task has privileged access rights. 

/RO Memory-resident overlay operator 
(!) is enabled. 

/SE Messages can be directed to the .TSK /SE 

task by means of the Executive 
SEND directive. 

1. The default is /MA for an input file, and /-MA for system library 
and resident library .STB files. 

2. The default for the memory management switch is /MM if the host 
system has memory managment hardware, and /-MM if the host system does 
not have m.emorv management hardware. 

(continued on next page) 
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.OLB 




/-LB 


.TSK 




/-LI 


.STB 






.MAP, 


/MA 


or /-MA^ 


.OBJ 






.TSK 


/MM 


or /-MM 2 


.ODL 




/-MP 


.TSK 




/-MU 


.TSK 




/-NM 


• TSK, 




/-PI 


.STB 






.TSK 




/-PM 


.TSK 




/-PR 


.TSK 




/RO 



SWITCHES 



Table 10-1 (Cont.) 
Task Builder Switches 



Applies 
^o^^^t Meaning to File Default 



/SH 


/-SL 


/SP 


/-SQ 



/SG Allocates task program sections .TSK /-SG 

alphabetically by access code (RW 
followed by RO) , 

/SH Short memory allocation file is .MAP 

requested, 

/SL Task is slaved to an initiating .TSK 

task. 

/SP Spool map output. .MAP 

/SQ Allocates task program sections .TSK 

in input order by access code. 

/SS Selective search for global .OBJ /-SS 

symbols . 

/TR Task is to be traced. .TSK /-TR 

/WI Memory allocation file is printed .MAP /wi 

at a width of 132 characters. 

/XH RSX-llM-PLUS only switch. Task is .TSK ^ 

to have an external header. 

/XT[:n] TKB exits after n diagnostic. .TSK /-XT 



3. The default IS ultimately determined by the /XHR switch in the 
.INSTALL command, which .overrides the TKB setting .except for /-XH..: / 
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AC 



10.1.1 /AC[:n] — Ancillary Control Processor 
File 

Task image 

Syntax 

file.TSK/AC:0=file.OBJ 

or 

£ile.TSK/AC:4=file.0BJ 

or 

file.TSK/AC:5=file.0BJ 

Description 

The /AC switch informs TKB that your task is an ancillary control 
processor; that is, it is a privileged task that extends certain 
Executive functions. For example, the system task FllACP is an 
ancillary control processor that receives and processes FILES-11 
related input and output requests on behalf of the Executive. 



Effect 



This switch also informs TKB that your task is privileged. TKB 
sets the AC attribute flag and the privileged attribute flag in 
your task's label block flag word. 

The value of n is an octal number that specifies the first KT-11 
Active Page Register (APR) that you want the Executive to use to 
map your task's image when your task is running in user mode. 
Legal values are 0, 4, and 5. If you do not specify n, the Task 
Builder assumes a value of 5. 

If you do not explicitly specify that your task is to run on a 
mapped system (through the /MM switch) and it is not otherwise 
implied (TKB is not running in a system with KT-11 hardware) , TKB 
merely tests the value of n for validity, but otherwise ignores 



it. 
Default 

/-AC 



NOTE 

You should not use /AC and /PR on the 
same command line. 
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10.1.2 /AL — Allocate Checkpoint Space 
File 

Task image 
Syntax 

file.TSK/AL=file,OBJ 
Description 



The /AL switch informs TKB that your task is checkpointable. The 
system will checkpoint it to a space in your task's image file. 
However, the system uses the system checkpoint file first if you 
specified dynamic checkpointing. 



Effect 



As well as making your task checkpointable, this switch directs 
TKB to allocate additional space in your task image file to 
contain the checkpointed task image. 



Default 

/-AL 



NOTES 

Do not use /CP in the same command line 
in which you use /AL. 

Also, the /AL switch should not be used 
with the /-HD switch to build tasks. 
Examples of tasks that use the /-HD 
switch are: the Executive, device 
drivers, and commons. 
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cc 



10.1.3 /CC — Concatenated Object Modules 
File 

Input 
Syntax 

file.TSK=file.OBJ/-CC 
Description 

/CC controls the way TKB extracts modules from your input file. 
Effect 

By default, TKB includes in your task's image all the modules of 
your input file. If you negate this switch (as in the Syntax 
section above) , TKB includes only the first module of your input 
file. 

Default 

/CC 
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10.1.4 /CM — Compatibility Mode Overlay Structure 
File 

Task image 
Syntax 

file.TSK/CM=file.OBJ 
Description 

/CM causes the Task Builder to build your task in compatibility 
mode. 



Effect 



TKB aligns memory-resident overlay segments on 256-word 
boundaries for compatibility with other implementations of the 
mapping directives. 



Default 

/-CM 
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10.1.5 /CO — Build a Common Block Shared Region 
File 

Task image 
.STB file 

Syntax 

file.TSK/CO=file.OBJ 
or 

, ,f ile.STB/CO=f ile.OBJ 
Description 

The /CO switch informs TKB that a shared common is being built. 
If you build a shared common, you should use the /CO switch and 

the /-HD switch. 

If you use the /-PI switch for an absolute shared common, all the 

program sections in the coitimon are marked absolute. Using the 

/-PI/-HD switches without the /CO switch causes TKB to build a 
shared library. 

If you use the /PI switch for a relocatable shared common, all 
program sections in the common are marked relocatable. 

In either case, the ,STB file contains all the program section 
names, attributes, length, and symbols. TKB links common blocks 
by means of program sections. Therefore, the .STB file of a 
shared region built with the /CO switch contains all defined 
program sections. 

Using the /PI/-HD switches without the /CO switch causes TKB to 
build a shared common. 

The /CO switch does not have a /-CO form. 

Effect 

This switch causes TKB to include all program section 
declarations in the .STB file. 

Defaults 

/CO 
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CP 

10.1.6 /CP ~ Checkpointable 
File 

Task image 
Syntax 

file.TSK/CP=file.OBJ 

Description 

/CP causes TKB to mark your task as checkpointable. The system 
will checkpoint it to space that you have allocated in the system 
checkpoint file on the system disk. This switch assumes that you 
have allocated the checkpoint space through the MCR command ACS. 
(Refer to the RSX-llM/M-PLUS MCR Operations Manual.) 



Effect 



The system writes your task to the system checkpoint file on 
secondary storage when its physical memory is required by a task 
of higher priority. 



Default 

/-CP 



NOTE 

Using /AL also makes your task 
checkpointable . 



10-10 



SWITCHES 



CR 



10.1.7 /CR — Cross-Reference 
File 

Memory allocation (map) 
Syntax 

file.TSK,f ile.MAP/CR=file.OBJ 

Description 

The /CR switch directs TKB to add a cross-reference listing to 
the map file of your task. 



Effect 



TKB creates a special work file (file.CRF) that contains segment, 
module, and global symbol information. The Task Builder then 
calls the Cross-Reference Processor (CRF) to process the file. 
CRF creates a cross-reference listing from the information 
contained in the file, and then deletes file.CRF. (Refer to the 
RSX-11 Utilities Manual for more information on CRF.) 

The Example section below describes the cross-reference listing 
and its contents. 



NOTE 

For this switch to be effective, CRF 
must be installed in your system. 



Default 

/-CR 
Example 



Example 10-1 shows a cross-reference listing for task OVR. The 
numbered items in the notes correspond to the numbers in Example 
10-1. 
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CR (Cont.) 



Example 10-1 Cross-Reference Listing for OVR.TSK 



CREF CREATED BY TKB 
GLOBAL CROSS REFERENCE 



ON 27-JUL-82 AT 09:46 



PAGE 1 
CREF vol 



SYMBOL 


VALUE 




REFERENCES 


■ • • 


AADD 


020000-R 


* 


AADD 


@ 


CALC 


ADDEXI 


020060-R 


* 


AADD 






ARGBLK 


001340-R 




CALC 


# 


MAIN 


BUFF 


001366-R 


# 


MAIN 




OUTPUT 


CALC 


003270-R 


* 


CALC 


(9 


MAIN 


DIFR 


001360-R 




CALC 


# 


MAIN 


DIVEXI 


020062-R 


* 


DIW 






DIVR 


001364-R 




CALC 


# 


MAIN 


DIVV 


020000-R 


@ 


CALC 


* 


DIW 


I 


001350-R 




INPUT 


# 


MAIN 


IE. EOF 


177766 




INPUT 


# 


QIOSYM 


INITL 


005664-R 


# 


INITL 


«v 


MAIN 


INPUT 


003364-R 


* 


INPUT 


@ 


MAIN 


lOSB 


001334-R 




INPUT 


# 


MAIN 



CREF CREATED BY TKB 
SEGMENT CROSS REFERENCE 
SEGMENT NAME RESIDENT MODULES 



ON 27-JUL-82 AT 09:46 



PAGE 2 
CREF vol 



AADD 


AADD 


CALC 


CALC 


DIVV 


DIVV 


INPUT 


ARITH 


LIBROT 


INITL 


MAIN 


ALERR 




VCTDF 


MULL 


MULL 


OUTPUT 


ARITH 




EDTMG 


SUBB 


SUBB 



CATB INPUT QIOSYM SAVRG 

SAVAL 

AUTO MAIN OVCTR OVDAT 



e 



CATB CBTA CDDMG 
OUTPUT QIOSYM SAVRG 



C5TA 



OVRES SAVRl 



DARITH EDDAT 



NOTES 

O The cross-reference page header gives the name of the memory 
allocation file, the originating task (TKB), the date and 
time the memory allocation file was created, and the 
cross-reference page number. 

The cross-reference list contains an alphabetic listing of 

each global symbol along with its value and the name of each 

referencing module. When a symbol is defined in several 
segments within an overlay structure, the last defined value 

is printed. Similarly, if a module is loaded in several 

segments within the structure, the module name is displayed 
more than once within each entry. 
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CR (Cont.) 



The suffix -R appears next to the value if the symbol is 
relocatable . 

Prefix symbols accompanying each module name define the type 
of reference as follows: 

Prefix Symbol Reference Type 

blank Module contains a reference that is 
resolved in the same segment or in a 
segment toward the root. 

Module contains a reference that is 
resolved directly in a segment away from 
the root or in a co-tree. 

@ Module contains a reference that is 

resolved through an autoload vector. 

# Module contains a nonautoloadable 
definition. 

* Module contains an autoloadable definition. 



Q The segment cross-reference lists the name of each overlay 
segment and the modules that compose it. If the task is a 
single-segment task, this section does not appear. 
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SWITCHES 

DA 

10.1.8 /DA — Debugging Aid 
File 

Task image or input 
Syntax 

file. TSK/DA=f i le . OBJ 
or 

file.TSK=file. OB J, file. OBJ/DA 

Description 

/DA causes TKB to include a debugging aid in your task. The 
debugging aid controls the task's execution. 



Effect 



If you apply this switch to your task image file, TKB includes 
the system debugging aid LBO: [1,1] DDT. OBJ into your task image. 
If you use the /DA switch with the /ID, switch, " TKB includes 
DBi£l,l]<X)TID.OBJ in the task. 

TKB passes control to the debugging program when you or the 
system starts task execution. 

If you apply this switch to one of your input files, TKB assumes 
that the file is a debugging aid that you have written. Such 
debugging programs can trace a task, printing out relevant 
debugging information, or monitor the task's performance for 
analysis. The default file type for the debugging aid is .OBJ. 

In either case, /DA has the following effects on your task image: 

• The transfer address of the debugging aid overrides the 
task transfer address. 

• TKB initializes the header of your task so that, on 
initial task load, registers RO through R4 contain the 
following values: 

RO - Transfer address of task. 

Rl - Task name in Radix-50 format (word #1) . 

R2 - Task name (word #2) . 

R3 - The first three of six RAD50 characters representing 
the version of your task. TKB derives the version 
from the first . IDENT directive it encounters in your 
task. If no .IDENT directive is in your task, this 
value is 01. 

R4 - The second three RAD50 characters representing the 
version of your task. 



Default 

/-DA 
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DL 



10.1.9 /DL — Default Library 
File 

Input 
Syntax 

file.TSK=file.OBJ,file.OLB/DL 
Description 

This switch causes the input file to be a replacement for the 
system object module library. The default file type for the 
input file is .OBJ. 

Effect 

The library file you have specified replaces the file 
LEO: [l,l]SySLIB.OLB as the library file that the Task Builder 
searches to resolve undefined global references. The default 
device for the replacement file is SYO : . TKB refers to it only 
when undefined symbols remain after it has processed all the 
files you have specified. You can apply the /DL switch to only 
one input file. 

Default 

/-DL 
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EA 



10.1.10 /EA — Extended Arithmetic Element 
File 

Task image 
Syntax 

file.TSK/EA=file.OBJ 
Description 

/EA informs TKB that your task uses the KEll-A Extended 
Arithmetic Element. 



Effect 



TKB allocates three words in your task's header for saving the 
state of the extended arithmetic element. 



Default 

/-EA 



NOTE 

You should not use /EA and /FP on the 
same command line. 
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10.1.11 /EL — Extend Library 
File 

Task image 
Syntax 

f i le .TSK/LI/-HD/EL=f i l6 . OBJ 

Description 

/EL places the upper address limit as determined by the PAR 
option in the library's label block, though the actual size of 
the library may be smaller. This switch is useful when you build 
vectored libraries such as RMS, which are subject to size 
changes. 



Effect 



This switch specifies the maximum possible size for the library 
according to the size specified in the PAR option. The switch 
specifies a larger library virtual address range than is actually 
present in the library to allow RMS to map its vectored library 
segments . 



Default 

/-EL 
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FP 



10.1.12 /FP — Floating Point 
File 

Task image 
Syntax 

file.TSK/FP=file.OBj 
Description 

/FP informs TKB that your task uses the Floating Point Processor. 

Effect 

TKB allocates 25 words in your task's header for saving the state 
of the Floating Point Processor. 

Default 

/-FP on RSX-llM systems 

/FP on RSX-liM-PLDS""systems "■ 

NOTES 



You should not use /FP and /EA on 
the same command line. 

The /FP switch allocates space in 
the task header to save the floating 
point status if your task is context 
switched. Therefore, in an RSX-llM 
system, if a task that uses the 
Floating Point Processor is built 
without the /FP switch, the task 
will run correctly until a second 
task that uses the Floating Point 
Processor is run. Then both tasks 
will either crash or produce 
incorrect results. For information 
on changing the Task Builder's 
defaults, refer to Appendix F. 
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10.1.13 /FU — Full Search 
File 

Task image 
Syntax 

file=TSK/FU=file.ODL/MP 
Description 

This switch controls the Task Builder's search for undefined 
symbols when it is processing modules from the default library. 



Effect 



When TKB processes modules from the default object module 
library, and it encounters undefined symbols within those 
modules, it normally limits its search for definitions to the 
root of the main tree and to the current tree. Thus, unintended 
global references between co-tree overlay segments are 
eliminated. When the /FU switch is appended to the task image 
file of an overlaid task, TKB searches all co-tree segments for a 
matching definition or reference. See Sections 3.2.2 and 3.2.3 
in Chapter 3 for more details. 



Default 

/-FU 
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10,1.14 /HD — Header 
File 

Task image or symbol definition 
Syntax 

file.TSK/-HD, , file. STB=file. OBJ 
or 

file.TSK,,file.STB/-HD=file.OBJ 

Description 

The /-HD form of this switch directs TKB to exclude a header from 
your task image. 

Effect 

TKB does not construct a header in your task image. You use the 
negated form of this switch when you are building commons, 
resident libraries, and loadable drivers. 



Default 

/HD 
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10.1.15 /ID ~ I- and D-space Task (RSX-llM-PLUS Only) 
File 

Task image 
Syntax 

f i lo .TSK/ID=f i l.e = OD J 

Description 

This switch direcLs TKB to tn-irk your task as one that uses 
1-sp.iCG APRS and D-spacR APRs in user mode. TKB separates 
I-PSECTs From D-?SECTs. 



Effect 



TKB includes the data structures in the task label block that 
informs INSTALL that the task has separate I-space and D-space. 



Default 

/-ID 
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10.1.16 /IP — Task Maps I/O Page 
File 

Task image 
Syntax 

file,TSK/PR/-IP=file.OBJ 
Description 



You use the /-IP switch to inform TKB that the task is purposely 
over 12K and does not need to be mapped to the I/O page. 



Effect 



TKB sets a bit in the task's label block that informs INSTALL 
(INS) that the task intentionally does not map the I/O page. 
When this bit is set, INS does not display an error message when 
it detects that the privileged task extends into APR 7. 



Default 

/IP 
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10.1.17 /LB — Library File 
File 

Input 
Syntax 

file. TSK=f i le . OBJ , f i le . OLB/LB 

or 

f ile.TSK=f ile.OBJjf ile.0LB/LB:mod-l:mod-2. . . :mod-8 

Description 

The file to which this switch is attached is an object module 
library file. The Task Builder's interpretation of this switch 
depends upon which of the following forms you use: 

• Without arguments (the first syntax given above) 

• With arguments (the second syntax given above) 
The default file type is .OLB. 

Effect 

If you apply this switch without arguments, TKB assumes that your 
input file is a library file of relocatable object modules. TKB 
searches the file immediately to resolve undefined references in 
any modules preceding the library specification. It also 
extracts from the library, for inclusion in the task image, any 
modules that contain definitions for such references. 

If you apply the switch with arguments, TKB extracts from the 
library the modules named as arguments of the switch regardless 
of whether the modules contain definitions for unresolved 
references . 

If you want TKB to search an object module library file both to 
resolve global references and to select named modules for 
inclusion in your task image, you must name the library file 
twice: once, with the modules you want included in your task 
image listed as arguments of the /LB switch; and a second time, 
with the /LB switch and no arguments. For example: 

f i le . TSK=f i le . OLB/LB :mod-l :mod-2 , f i le . OLB/LB 
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The position of the library file within TKB command sequence is 
important. The following rules apply: 

• The library file must follow to the right of the input 
file(s) that contain references to be defined in the 
library. For example: 

TKB>file.TSK=infilel.OBJ,lib.OLB/LB 

The command above illustrates the correct usage of the /LB 
switch; the following command illustrates incorrect usage: 

TKB>file.TSK=lib,OLB/LB,f ilel.OBJ 

• If you are using the Task Builder's multiline input, and 
you specify a given library more than once during the 
command sequence, you must attach the /LB switch to the 
library file each time you specify the library. For 
example: 

>TKB 

TKB>file.TSK=filel.OBJ,f ile2.0BJ,lib.0LB/LB 

TKB> f i le3 . OBJ , f i le4 . OBJ , 1 ib . OLB/LB 

// 

• When you are building an overlay structure, you must 
specify object module libraries for an overlay structure 
within the Overlay Description Language (ODL) file for the 
structure. To do this, you must use the .FCTR directive to 
specify the library. For example: 

.ROOT CNTRL-LIB-(AFCTR,BFCTR,C) 
AFCTR: .FCTR AO-LIB- (Al ,A2- (A21 ,A22) ) 
BFCTR: .FCTR BO-LIB- (B1,B2) 
LIB: .FCTR LB : [303 , 3] LIBOBJ .OLB/LB 

.END 

The technique used in the ODL file above allows you to control 
the placement of object module library routines into the 
segments of your overlay structure. (For more information on 
overlaid tasks, see Chapter 3.) 



NOTES 



1. You should not use the /LB switch 
and the /CC switch in the same 
command sequence. 

2. You can use the /SS switch in 
conjunction with the /LB switch 
(with or without arguments) to 
perform a selective search for 
global definitions. 



Default 

/-LB 
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10.1.18 /LI — Build a Library Shared Region 

File 

Task image 
.STB file 

Syntax 

file.TSK/LI=file.OBJ 
or 

,,file.STB/LI=file.OBJ 

Description 

The /LI switch makes TKB build a shared library. However, you 
must use the /-HD switch with the /LI switch to build the shared 
library. The /LI switch does not have a /-LI form. 



Effect 



TKB includes only one program section declaration in the .STB 
file. 

If you use the /-PI switch for an absolute library, TKB names the 
program section . ABS, makes the library position dependent, and 
defines all symbols as absolute. Also, if you use the /-PI 
switch without the /LI switch, TKB assumes /LI to be the default. 

If you use the /PI switch for a relocatable library, TKB names 
the program section the same as the root segment of the library. 
TKB forces this name to be the first and only declared program 
section In the library. TKB declares all global symbols in the 
.STB file relative to that program section. Also, if you use the 
/PI switch without the /LI switch, TKB assumes that a shared 
common is to be built (/CO is the default) . 



Default 

/-LI 
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10.1.19 /MA — Map Contents of File 
File 

Input or memory allocation 
Syntax 

file.TSK,file.MAP=file.OBJ,file.OBJ/-MA 
or 

file.TSK,file.MAP/MA=file.OBj 

Description 

TKB is to include information from your input file in the memory 
allocation output file. 

Effect 

If you negate this switch and apply it to an input file, TKB 
excludes from the map and cross-reference listings all global 
symbols defined or referred to in the file. In addition, TKB 
does not list the file in the "file contents" section of the map. 

If you apply this switch to the map file, TKB includes in the map 
file the names of routines it has added to your task from SYSLIB. 
It also includes in the map file information contained in the 
symbol definition file of any shared region to which the task 
refers . 

Default 

/MA for input files 

/-MA for system library and resident library STB files 
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10.1.20 /MMt:n] — Memory Management 
File 

Task image 
Syntax 

file.TSK/MM[:n]=file.OBJ 

or 

file.TSK/-MM[:n]=file.OBJ 

Description 

The /MM switch informs TKB whether the system on which your task 
is to run has memory management hardware. Specify n as the 
decimal numbers 28 or 30. 

Effect 

If you use n with the /-MM switch (for an unmapped system) , n 
specifies the highest physical address in K-words of the task or 
system being built. If you do not specify n with /-MM, the 
default highest address of the task or system is 28K. 

If you specify n with /MM, n is ignored. 

Default 

When you do not apply /MM or /-MM to your task image file, TKB 
allocates memory according to the mapping status of the system on 
which your task is being built. The maximum task size for a 
mapped system is always 32K. The default highest address for a 
task or system in an unmapped system is 28K. 

NOTE 

When you use /-MM, TKB does not recognize the 

memory-resident overlay operator(!). TKB checks the 

operator for correct syntax, but it does not create any 
resident overlay segments. 
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10.1.21 /MP — Overlay Description 
File 

Input 
Syntax 

f ile . TSK=f lie .ODL/MP 

Description 

The /MP switch specifies that the input file is an Overlay 
Description Language (ODL) file. 

Effect 

TKB receives all the input file specifications from this file. 
It allocates virtual address space as directed by the overlay 
description. If you use the Task Builder's multiline command 
format (see Section 1.3) , TKB requests option information at the 
console terminal by displaying: 

ENTER OPTIONS:. 



NOTES 



If you use the multiline command 
format when you specify an ODL file, 
TKB automatically prompts for option 
input. Therefore, you must not use 
the single slash (/) to direct TKB 
to switch to option input mode when 
you have specified /MP on your input 
file. 

When you specify /MP on the input 
file for your task, it must be the 
only input file that you specify. 
The default file type is .ODL. 



Default 

/-MP 
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10.1.22 /MD — Multiuser (RSX-llM-PLDS Only) 

File :' 

Input 

'Syntax ■■ ■ 

^: /file. Tfc:K/MU=file. OBJ 

^pescription 

/': ,' The /MU switch specifies to TKB that the task is / aV inuitiuser' 
■ ', .// ."task. .„ .'.■ {.'.- ■:' 



Effect 



TKB separates your task's read-only and read/write program 
sections. Tt then places the read-only program sections in- yout: 
task's upper virtual address space and the read/Wxite. program 
sections in your task's lower virtual address space. -, • 



Def aul t 

/-MU 
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10.1.23 /RH — No Diagnostic Messages 
File 

Task image 
Syntax 

file.TSK/NM=file.OBJ 
Description 

The /NM switch controls the printing of diagnostic messages. 
Effect 

This switch eliminates two messages: 
n Undefined symbols segment seg-name 

and 

Module module-name multiply defines P-section p-sect-name 
Default 

/-NM 
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10.1.24 /PI — Position Independent 
File 

Task image or symbol definition 
Syntax 

file.TSK/PI=file.OBJ 
or 

file.TSK,,file.STB/PI=file.OBJ 
Description 

/PI informs TKB that the task's shared region contains only 
position-independent code or data. Use this switch with /-HD and 
either /CO or /LI. 



Effect 



TKB sets the position-independent code (PIC) attribute flag in 
the label block flag word of the shared region. 

Be aware that if you specify /PI without using the /CO or /LI 
switches, TKB builds a shared common (/CO default) . Also, if you 
specify /-PI without using the /CO or /LI switch, TKB builds a 
shared library (/LI default) . 



Default 

/-PI 
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PM 

10.1.25 /PM — Postmortem Dump 
File 

Task image 
Syntax 

file.TSK/PM=file.OBJ 

Description 

If you use /PM and your task terminates abnormally, the system 
automatically lists the contents of the memory image. 

Effect 

TKB sets the Postmortem Dump flag in your task's label flag word. 

NOTES 

1. If your task issues an ABRT$ (abort 
task) directive, the system will not 
dump the task image even though TKB 
has set the Postmortem Dump flag in 
your task's label flag word. In 
this case, the system assumes that a 
Postmortem Dump is not necessary 
since you know why your task was 
aborted . 

2. The PMD utility must be installed in 
your system and be able to get into 
physical memory for this switch to 
be effective. 

Default 

/-PM 
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10.1.26 /PR[:n] — Privileged 
File 

Task image 
Syntax 

f ile.TSK/PR:0=f ile .OBJ 
or 

file.TSK/PR:4=file.0BJ 
or 

file.TSK/PR:5=file.0BJ 
Description 



The /PR switch informs TKB that your task is privileged with 
respect to memory and device access rights. If you specify PR:0, 
your task does not have access to the I/O page or the Executive. 
However, if you specify PR:4 or PR:5, your task does have access 
to the I/O page and the Executive, in addition to its own 
partition. 

Effect 

TKB sets the Privileged Attribute flag in your task's label block 
flag word. 

The value of n is an octal number that specifies the first Active 
Page register that you want the Executive to use to map your task 
image when your task is running in user mode. Legal values are 
0, 4, and 5. If you do not specify one of these values, TKB 
assumes a value of 5. 

If you do not explicitly specify that your task is to run on a 
mapped system, (through the /MM switch) and it is not implied (by 
the presence of KT-11 hardware on the system upon which TKB is 
running), TKB merely tests the value (:n) of the switch for 
validity; otherwise, TKB ignores it. Privileged tasks are 
described in Chapter 9. 

Default 

/-PR 

NOTE 

YOU should not use /PR and /AC on the 
same command line. 
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10.1.27 /RO — Resident Overlay 
File 

Task image 
Syntax 

file.TSK/-RO=file.ODL/MP 
Description 

The Task Builder's recognition of the memory-resident overlay 
operator (!) is enabled. 



Effect 



The memory-resident overlay operator (!), when present in the 
overlay description file, indicates to TKB that it is to 
construct a task image that contains one or more memory-resident 
overlay segments. If you negate this switch (as in the Syntax 
section above) , TKB checks the operator for correct syntactical 
usage, but otherwise ignores it. With the memory-resident 
overlay operator thus disabled, TKB builds a disk-resident 
overlay from the overlay description file. 



Default 
/RO 
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10.1.28 /SE ~ Send 
File 

Task image 
Syntax 

file.TSK/-SE=file.OBJ 
Description 

This switch determines whether messages can be directed to your 
task by means of the Executive Send directive. (Refer to the 
RSX-llM/M-PLUS Executive Reference Manual for information on the 
Send directive) 



Effect 



By default, messages can be directed to your task by means of the 
Executive Send directive. If you negate this switch (as in the 
Syntax section above) , the system inhibits the queuing of 
messages to your task. 



Default 

/SE 



10-35 



SWITCHES 

SG 

10.1.29 /SG — Segregate Program Sections 
File 

Task image 
Syntax 

file.TSK/SG=file.OBJ 
Description 

The /SG switch allocates virtual address space to all (RW) 
program sections and then to all read-only (RO) program sections. 



Effect 



The /SG switch gives you control over the ordering of program 
sections. By using the /SG switch, you cause TKB to order 
program sections alphabetically by name within access code (RW 
followed by RO) . If you specify the /SQ switch with the /SG 
switch, TKB orders program sections in their input order by 
access code. See the description of the /SQ switch. 

You use the negated switch, /-SG, to make TKB interleave the RW 
and RO program sections. Thus, the combination /-SG/SQ results 
in a task with its program sections allocated in input order and 
its RW and RO sections interleaved. Additionally, you can use 
/-SQ/-SG to make TKB order program sections alphabetically with 
RW and RO sections interleaved. However, /-SG is the default. 

When taskbuilding multiuser tasks, the /MU switch causes TKB to 
default to /SG. Therefore, to correctly build read-only tasks, 
you can use the /MU switch only. 



Default 

/-SG 
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10.1.30 /SH — Short Map 
File 

Memory allocation (map) 
Syntax 

file.TSK,file.MAP/SH=file.OBJ 

Description 

If you specify /SH, TKB produces the short version of the memory 
allocation file. 

Effect 

TKB does not produce the "file contents" section of the memory 
allocation file. 

Default 

/SH 
Example 

The memory allocation file consists of the following items: 

• Page header 

• Task attributes section 

• Overlay description (if applicable) 

• Root segment allocation 

• Tree segment description (if applicable) 

• Undefined references (if applicable) 

• Task Builder statistics 

An example of the memory allocation file (map) is shown in 
Example 10-2. The numbered and lettered items in the notes 
correspond to the numbers and letters in Example 10-2. 

Example 10-2 Memory Allocation File (Map) Example 

0VR.TSK;1 Memory Allocation Map TKB M40.10 Page 1 Q 

15-DEC-82 11:28 1 

Partition name : GEN (a) (b) 

Identification : 01 © 

Task UIC : [303,3]® ® _ 

Stack limits: 000260 001257 001000 00512.;!. 

(continued on next page) 
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Example 10-2 (Cont.) Memory Allocation File (Map) Example 



Prg xfr address: 001264 @ ® © 

Total address windows: 1, ® (k) 

Task image size : 7488. words (m) (n) 

Task address limits: 000000 035107 @ 

R-W disk blk limits: 000002 000073 000072 00058. (p) (q) 

OVR.TSK Overlay description: 



o 



Base 

000000 
005034 
005034 
021060 
021060 

OVR.TSK 
ROOTM 



Top 

005033 
021057 
021057 
035103 
035107 



Length 



005034 
014024 
014024 
014024 
014030 



02588. 
06164. 
06164. 
06164. 
06168. 



ROOTM 
MULOV 
ADDOV 
SUBOV 
DIVOV 



Memory allocation map TKB M40.02 
28-DEC-81 09:10 



*** Root segment: ROOTM (a) 

R/W mem limits: 000000 005033 005034 02588.® 
Disk blk limits: 000002 000007 000006 00006.® 

Memory allocation synopsis: 



Section 



BLK. 



ANS 



@ 

; (RW,I,LCL,REL,CON) 001260 002514 01356. 

001260 000102 00066. 

001362 000260 00176. 

001642 000042 00034. 

003774 000002 00002. 

(RW,D,GBL,REL,OVR) 003774 000002 000002, 

003774 000002 00002. 

003774 000002 00002. 



Global Symbols: 

AADD 004032-R DIVV 
MOLL 



e 



Page 2 



Title Ident File 



ROOTM 
PRNOV 
SAVOV 



ROOTM 
PRNOV 



01 ® ROOTM. OBJ; 1 
01 PRNOV. OBJ ;1 
01 SAVOV. OBJ; 1 



01 
01 



ROOTM. OB J; 1 
PRNOV. OBJ ;1 



004052-R PRINT 001550-R 
004022-R SAVAL 001642-R 



OVR.TSK 
MULOV 



Memory allocation map TKB M40.02 Page 3 
28-DEC-81 09:10 



SUBB 004042-R ® 

D ® ® ® ® 



*** Cf^n- 






R/W mem limits: 005034 021057 014024 06164. 
Disk blk limits: 000010 000024 000015 00013. 



@ 



(continued on next page) 
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Example 10-2 (Cont.) Memory Allocation File (Map) Example 



Memory allocation synopsis: 
Section 



Title Ident File 



. BLK. : (RW,I,LCL,REL,CON) 005034 014024 06164. 

005034 014024 06164. MULOV 01 

$$ALVC: (RW,D,LCL,REL,CON) 021060 000000 00000. 

$$RTS : (RW, I,BGL,REL,OVk) 004250 000002 00002. 



Global symbols: 
MULL 021034-R 



M0L0V.0BJ;1 



*** Task builder statistics: 

Total work file references: 7156. (S) 
Work file reads: 



Work file writes: 
Size of core pool: 
Size of work file: 



S:f 






7086. words (27. pages) (d) 
3072. words (12. pages) (^ 



ELAPSED TIME:00:00:14 



© 



Notes ; 



O The page header shows the name of the task image file and the 
overlay segment name (if applicable), along with the date, 
time, and version of TKB that created the map. 

The task attributes section contains the following 
information : 

(a) Task name — The name specified in the TASK option. If 
you do not use the TASK option, TKB suppresses this 
field. 

(b) Partition name — The partition specified in the PAR 
option. If you do not specify a partition, the default 
is partition GEN. 

(c) Identification — The task version as specified in the 
.IDENT assembler directive. If you do not specify the 
task identification, the default is 01. 

(3) Task UIC — The task UIC as specified in the UIC option. 
If you do not specify the UIC, the default is the 
terminal UIC. 
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(e) Task priority — The priority of the task as specified in 
the PRI option. If you do not specify PRI, the default 
is 50, and is not shown on the map. 

Stack limits — The low and high octal addresses of the 
stack, followed by its length in octal and decimal bytes. 

(g) ODT transfer address — The starting address of the ODT 
debugging aid. If you do not specify the ODT debugging 
aid, this field is suppressed. 

(h) Program transfer address — The address of the symbol 
specified in the .END directive of the source code of 
your task. If you do not specify a transfer address for 
your task, TKB automatically establishes a tranfer 
address of 000001 for it. TKB also suppresses this field 
in the map if you do not specify a transfer address. 

® Task attributes — These attributes are listed only if 
they differ from the defaults. One or more of the 
following may be displayed: 

AC Ancillary control processor. 

AL Task is checkpointable, and task image file 
contains checkpoint space allocation. 

CP Task is checkpointable, and task image file 
will be checkpointed to system checkpoint file. 

DA Task contains debugging aid. 

EA Task uses KEll-A extended arithmetic element. 

FP Task uses Floating Point Processor. 

-HD Task image does not contain header. 

PI Task contains position-independent code and 
data . 

PM Postmortem Dump requested in the event of 
abnormal task termination. 

PR Task is privileged. 

-SE Messages addressed to the task through the SEND 
directive will be rejected by the Executive. 

SL Task can be slaved. 

TR Task initial PS word has T-bit enabled. 

ID Task is I- and D-space task. 

® Total address windows — The number of window blocks 
allocated to the task. 
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(k) Mapped array — The amount of physical memory (decimal 
words) allocated through the VSECT option or Mapped Array 
Declaration (GSD type 7, described in Appendix B) ; 
mapped array is not shown if it does not apply. 

CD Task extension — The increment of physical memory 

(decimal words) allocated through the EXTTSK or PAR 

option. Without these options, task extension is not 
shown. 

@ Task image size — The amount of memory (decimal words) 
required to contain your task's code. This number does 
not include physical memory allocated through the EXTTSK 
option. 

(n) Total task size — The amount of physical memory (decimal 

words) allocated, including mapped array area and task 

extension area. Total task size is not shown in this 
example. 

(o) Task address limits — The lowest and highest virtual 
addresses allocated to the task, exclusive of virtual 
addresses allocated to VSECTs and shared regions. 

(p) Read/write disk block limits — From left to right: the 
first octal relative disk block number of the task's 
header; the last octal relative disk block number of the 
task image; and the total contiguous disk blocks 
required to accommodate the read/write portion of the 
task image in octal and decimal. 

(q) Read-only disk block limits — From left to right: the 
first octal relative disk block of the multiuser task's 
read-only region; the last octal relative disk block 
number of the read-only region; and the total contiguous 
disk blocks required to accommodate the read-only region 
in octal and decimal. This field appears only when you 
are building a multiuser task. 

The overlay description shows, for each overlay segment in 
the tree structure of an overlaid task, the beginning virtual 
address (the base) , the highest virtual address (the top) , 
the length of the segment in octal and decimal bytes, and the 
segment name. Indenting is used to illustrate the ascending 
levels in the overlay structure. TKB prints the overlay 
description only when an overlaid task is created. 

The root segment allocation — This section has the following 
elements : 

(a) Root segment — The name of the root segment. If your 
task is a single-segment task, the entire task is 
considered to be the root segment. 

(b) Read/write memory limits — From left to right: the 
beginning virtual address of the root segment (the base) ; 
the virtual address of the last byte in the segment (the 
top) ; and the length of the segment in octax anu i^iecimaj. 

bytes. 
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© Disk block limits — From left to right: the first 
relative block number of the beginning of the root 
segment; the last relative block number of the root 
segment; total number of disk blocks in octal; and the 
total number of disk blocks in decimal. 

(d) Memory allocation synopsis — From left to right: the 
program section name; the program section attributes; 
starting virtual address of the program section; and 
total length of the program section in octal and decimal 
bytes. 

The program section shown as . BLK. in this field is the 
unnamed relocatable program section. Notice in this 
example that there are 636 (octal) bytes allocated to it 
(2034 bytes - 1176 bytes = 636 bytes) . This allocation 
is the result of calls to routines that reside within the 
unnamed program section in SYSLIB. (For more 
information, see the description of the /MA switch in 
Section 10.1.14.) 

@ Module contributor — This field lists the modules that 
have contributed to each program section. In this 
example, the program section ANS was defined in module 
ROOTM. The module version is 01 (as a result of the 
.IDENT assembler directive) and the file name from which 
the module was extracted is ROOTM. OBJ; 1. If the program 
section ANS had been defined in more than one module, 
each contributing module and the file from which it was 
extracted would have been listed here. 



NOTE 

The absolute section . ABS. is not shown because 
it appears in every module and always has a 
length of 0. 



® The global symbols section lists the global symbols 
defined in the segment. Each symbol is listed along with 
its octal value. A -R is appended to the value if the 
symbol is relocatable. The list is alphabetized in 
columns. 

The file contents section (which is composed of the four 

fields listed below) is printed only if you specify /-SH in 

the TKB command sequence. TKB creates this section for each 

segment in an overlay structure. It lists the following 
information : 

(D Input file — File name, m.odule name as established by 
the .TITLE assembler directive, and module version as 
established by the .IDENT assembler directive. 

(h) Program section — Program section name, starting virtual 
address of the program section, ending virtual address of 
the program section, and length in octal and decimal 
bytes . 
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® Global symbol — Global symbol names within each program 
section and their octal values. If the segment is 
autoloadable (see Chapter 3) , this value is the address 
of an autoload vector. The autoload vector in turn 
contains the actual address of the symbol, 

A -R is appended to the value if the symbol is 
relocatable. 

(T) Program section — The contents of this field is 
described in note g above. 

(k) Undefined References — This field lists the undefined 
global symbols in the segment. 

The tree segment description is printed for every overlay 
segment in an overlay structure. Its contents are the same 
for each overlay segment as the root segment allocation is 
for the root segment. 

Task builder statistics lists the following information, 
which can be used to evaluate TKB performance: 

(a) Work file references — The number of times that TKB 
accessed data stored in its work file. 

(D Work file reads — The number of times that the work file 
device was accessed to read work file data. 

® Work file writes — The number of times that the work 
file device was accessed to write work file data. 

(d) Size of pool — The amount of memory that was available 
for work file data and table storage. 

(e) Size of work file — The amount of device storage that 
was required to contain the work file. 

Elapsed time — The amount of wall-clock time required to 
construct the task image and produce the memory 
allocation (map) file. Elapsed time is measured from the 
completion of option input to the completion of map 
output. This value excludes the time required to process 
the overlay description, parse the list of input file 
names, and create the cross-reference listing (if 
specified) . 

See Appendix F for a more detailed discussion of the work file. 
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10.1.31 /SL — Slave 
File 

Task image 
Syntax 

file.TSK/SL=file.OBJ 

Description 

This switch directs TKB to mark your task as a slave to an 
initiating task. 



Effect 



TKB attaches the slave attribute to your task. When your task 
successfully executes a Receive Data directive, the system gives 
the UIC and TI : device of the sending task to it. The slave 
task then assumes the identity and privileges of the sending 
task. 

This switch only applies to your task if the system that you are 
using has multiuser protection. (Refer to your system generation 
manual for more information on multiuser protection and slave 
tasks . ) 



Default 

/-SL 
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10.1.32 /SP — Spool Map Output 
File 

Memory allocation (map) 
Syntax 

file.TSK,file.MAP/-SP=file.OBJ 

Description 

This switch determines whether TKB calls the print spooler to 
spool your memory allocation (map) file after task build. 



Effect 



By default, when you specify a map file in a TKB command 
sequence, TKB creates a map file on device SYO: and then has the 
file queued for listing on LPO : . 

If you negate this switch (as shown in the Syntax section above) , 
TKB creates the map file on device SYO: but does not call the 
print spooler to output it to LPO: 



Default 

/SP 



NOTE 

The PRT task must be installed to 
process the request to print the map. 
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10.1.33 /SQ — Sequential 
File 

Task image 
Syntax 

file.TSK/SQ=file.OBJ 

Description 

This switch causes TKB to construct your task image from the 
program sections you specified, in the order that you input them. 



Effect 



If you use this switch, TKB collects all the references to a 
given program section from your input object modules, groups them 
according to their access code (RW followed by RO) and, within 
these groups, allocates memory for them in the order that you 
input them. However, the /SG switch affects program section 
ordering and can be used with the /SQ switch. See the /SG switch 
for further details. 

Without the /SQ switch, TKB reorders the program sections 
alphabetically. 

You use this switch to satisfy any adjacency requirements that 

existing code may have when you are converting it to run under 

RSX-11. Using this feature is otherwise discouraged for the 
following reasons: 

• Standard library routines (such as FORTRAN I/O handling 
routines and FCS modules from SYSLIB) do not work properly. 

• Sequential allocation can result in errors if you alter the 
order in which modules are linked. 

Alternatively, you can achieve physical adjacency of program 
sections by selecting names alphabetically to correspond to the 
desired order. 



Default 

/-SQ 
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10.1.34 /SS — Selective Search 
File 

Input 
Syntax 

file.TSK=file.OB.J,file.OBJ/SS 
or 

file.TSK=file.OBJ,file.STB/SS 
or 

file.TSK=file.OBJ,file.OLB/LB/SS 

Description 

The /SS switch directs TKB to include in its internal symbol 
table only those global symbols for which there is a previously 
undefined reference. 



Effect 



When processing an input file, TKB normally includes in its 
internal symbol table each global symbol it encounters within the 
file whether or not there are references to it. With the /SS 
switch attached to an input file, TKB checks each global symbol 
it encounters within that file against its list of undefined 
references. If TKB finds a match, it includes the symbol in its 
symbol table . 



Default 

/-SS 
Example 



Assume that you are building a task named SEL.TSK. The task is 
composed of input files containing global entry points and 
references (calls) to them as shown in Table 10-2. 



Table 10-2 
Input Files for SEL.TSK 



Input 
File Name Global Definition Global Reference 



INI 

A 
IN2 B 

C 
IN3 
IN4 A 

B 

C 
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File IN2 and IN4 contain global symbols of the same name that 
represent entry points to different routines within their 
respective files. Assume that you want TKB to resolve the 
reference to global symbol A in INI to the definition for A in 
IN2. Assume further that you want TKB to resolve the reference 
to global symbol C in IN3 to the definition for C in IN4. By 
selecting the sequence of the input files properly and applying 
the /SS switch to files IN2 and IN4, TKB resolves the references 
correctly. The following command sequence illustrates the 
correct sequence: 

TKB>SEt, . TSK= INI . OBJ , IN2 . OB J/SS , IN3 . OBJ , IN4 . OB J/SS 

TKB processes input files from left to right; therefore, in 
processing the above command sequence, TKB processes file INI 
first and encounters the reference to symbol A. There is no 
definition for A within INI; therefore, TKB marks A as undefined 
and moves on to process file IN2. Because the /SS switch is 
attached to IN2, TKB limits its search of IN2 to symbols it has 
previously listed as undefined, in this case, symbol A. TKB 
finds a definition for A and places A in its symbol table. 
Because there are no undefined references to symbols B or C, TKB 
does not place either of these symbols in its symbol table. 



NOTE 

It is important to realize that the /SS 
switch affects only the way the Task 
Builder constructs its internal symbol 
table. The routines for which symbols B 
and C are entry points is included in 
the task image even though there are no 
references to them. 



TKB moves on to IN3. It encounters the references to symbol C. 
Because TKB did not include symbol C from IN2 in its symbol 
table, it cannot resolve the reference to C in IN3. TKB marks 
symbol C as undefined and moves on to IN4. 

When TKB processes IN4, it encounters the definition for C in 

that file and includes it in the table. Again, since the /SS 

switch is attached to IN4, TKB includes only C in its symbol 
table. 

When TKB has completed its processing of the above command 
sequence, it has constructed a task image composed of all of the 
code from all of the modules, INI through IN4. However, only 
symbols A from IN2 and C from IN4 will appear in its internal 
symbol table. 
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NOTE 

The example above does not represent 
good prograiraning practice. It is 
included here to illustrate the effect 
of the /SS switch on TKB during a search 
sequence. 



The /SS switch is particularly valuable when used to limit the 
size of the Task Builder's internal symbol table during the 
building of a privileged task that references the Executive's 
routines and data structures. By specifying the Executive's 
Symbol Definition File (STB) as an input file and applying the SS 
switch to it, TKB includes in its internal symbol table only 
those symbols in the Executive that the task references. An 
example of a TKB command sequence that illustrates this is shown 
below: 

TKB>0UTFILE.TSK/PR:5=INFILE.0BJ,RSX11M.STB/SS 

The above command sequence directs TKB to build a privileged task 
named OUTFILE.TSK from the input file INFILE.OBJ. The 
specification of the Executive's STB file as an input file with 
the SS switch applied to it directs TKB to extract from 
RSXllM.STB only those symbols for which there are references 
within OUTFILE.TSK. 
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10.1.35 /TR — Traceable 
File 

Task image 
Syntax 

file.TSK/TR=file.OBJ 
Description 

This switch directs TKB to make your task traceable. 
Effect 

TKB sets the T-bit in the initial PS word of your task. When 
your task is executed, a trace trap occurs when each instruction 
is completed. 

Default 

/-TR 
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10.1.36 /WI — Wide Listing Format 
File 

Memory allocation (map) 

Syntax 

file.TSK,file.MAP/-WI=file.OBJ 

Description 

This switch controls the width of your map file. 

Effect 

By default, TKB formats a map file 132 columns wide. When you 
negate this switch (as in the Syntax section above) , TKB formats 
the map file 80 columns wide. 

Default 

/WI 
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:iO;. 1.37 ,,/XH-- ; External Heacler fRSX-llM-PLUS bhlyj; 

.:File: ;. ••• • ..:'■■..:'■; , ;i' ■.:-'■■ Jr.- :'■;■;'■ 

■ . ■- Task- image: ■ 
■Syntax-.-; ■■■■■■ \; ■',, 

'; i^- ■'■ ' ;'f i le .:TSK/-XH= i-f i le..pBj ■ - ;■ • ■ ^ :\ ; 
"DescEiptibti' . ','■""':■;•'■■- .'."''''■' -i... .'' /r,'"' *' ■■..;",:'"■:■'---'',',/"' ' 

.' ",'Tl3e- /-XH syritch informs TKB that the' taslc is'rnot .to ' have^'an 

-j-' ;*ex-terna;r;head€r ."■.'■■ ■ .--;.."'■■ ■-■.■. '■ ■;■:''..'': .■■-;■»."::;■■•.: 

;Ejffect- '-■;;■■ ■:■.:■ ■• •' r;,- 

'; In an RSX-ilM- PLUS system, the effect of the /XH switch- is 
two-fold: -the header space in the task image is not destroyed 
when the- task is checkpointed; and . Executive pool space is 
conserved. A task built with the /XH switch does not have- a 
header in Executive pool, but has a copy of its header, which the 
Executive uses, in space allocated physically contiguous to and 
below the task image. When the task is checkpointed, the system 
writes the entire task image and the header copy below the task 
into a checkpoint file. The header in the task image is left 
unchanged . 

Note that if the task is also built with the /FP switch, the 
floating-point save area is not included in the task image but is 
in the header copy found below the task image. 

Interaction with the INSTALL command: 

On RSX-llM-PLUS, the INSTALL switch /XHR interacts with the TKB 
switch /XH. If, you use /-XH, the task will have a pool-resident 
header always unless you rebuild the task to have an external 
header. If you use /XH, the task will have an external header, 
but the INSTALL switch /XHR can override this. The default use 
of /XH by TKB is /XH (external header) unless this is changed by 
the INSTALL command. 

Default ■ " : 

/XH for RSX-llM-PLUS; overridden by /XHR on INSTALL 
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10.1.38 /XT[:n] — Exit on Diagnostic 
File 

Task image 
Syntax 

file.TSK/XT:4=file.0BJ 

Description 

This switch specifies the number of acceptable errors. More than 
n errors are not acceptable. 

Effect 

TKB exits after encountering n errors. The number of errors can 
be specified as a decimal or octal number, using the convention: 

n. indicates a decimal number (the decimal point must 
be included) . 

#n or n indicates an octal number. 

If you do not specify n, TKB assumes that n is 1. 

Default 

/-XT 
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11.1 OPTIONS 

Task Builder options provide you with the means to give TKB 
information about the characteristics of your task. 

These options, which are listed in Table 11-1, can be divided into 
seven categories. The identifying abbreviation and a brief 
description of each category are listed below: 

• contr You use control options to affect TKB execution. 

ABORT is the only member of this category. You can 
direct the Task Builder to abort the task build 
with this option. 

• ident You use identification options to identify your 

task's characteristics. You can specify the name 
of your task, its priority, user identification 
code, and partition with options in this category. 

• alloc You use allocation options to modify your task's 

memory allocation. With the options in this 
category, you can change the size of your task's 
stack and program sections. When you write 
programs in a high-level language, you can change 
the size of your work areas and buffers and declare 
the virtual base address and size of program 
sections. Finally, you can declare the number of 
additional window blocks (if any) that your task 
requires. 

• share You use storage-sharing options to indicate to TKB 

that your task intends to access a shared region. 

• device You use device-specifying options to specify the 

number of units required by your task, and the 
assignment of logical unit numbers to physical 
devices . 

• alter You use the content-altering options to define a 

global symbol and value, or to introduce patches in 
your task image. 

• synch You use synchronous trap options to define 

synchronous trap vectors. 

Some TKB options are of interest to all users of the system; others 
are of interest only to high-level language programmers; and still 
others are of interest only to MACRO-11 programmers. Table 11-1 lists 
all the options alphabetically, and gives a brief description of each. 
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Table 11-1 
Task Builder Options 



Option 



Meaning 



Interest^ 



ABORT Directs TKB to terminate a task build 

ABSPAT Declares absolute patch values 
for conventional tasks or 
I-spacB in 'I-and' D-space tasks 

ACTFIL Declares number of files open 
simultaneously 

ASG Declares device assignment to 
logical units 

CLSTR Declares a group of shared regions 

accessed by the task and residing in 

the same virtual address space in 
the task 

CMPRT^ iifcl.irpj corapL'-tiwn routine- for 

supTVisot-mod" lilic-jry 

COMMON Declare task's intention to access 
LIBR a memory-resident shared region 

DSPPAT Declares absolute patch values for, 
conventional tasks or l^^^^^sf^iprf 

EXTSCT Declares extension of a program 
section 

EXTTSK Declares extension of the amount of 
memory owned by a task 

FMTBUP Declares extension of buffer used 
for processing format strings 
at run time 

GBLDEF Declares a global symbol definition 

GBLINC Includes symbols in the .STB file 

GBLPAT Declares a series of patch values 
relative to a global symbol 

GBLREF Declares a global symbol reference 



H,M 
M 

H 

H,M 

H,M 

H,H 

H,M 



H,M 



H,M 



M 
M 
M 



Category 



contr 
alter 

alloc 

device 

share 

I'lent 

share 
alter 

alloc 
alloc 
alloc 

alter 
alter 
alter 



H,M alter 

(continued on next page) 



1. The user interest range is indicated as follows: 

• H indicates options of interest to high-level language (such 
as FORTRAN) programmers. 

• M indicates options of interest to MACRO-11 programmers. 

2. These options are applicable to RSX-llM-PLUS systems only. 
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Table 11-1 (Cont.) 
Task Builder Options 



Option 



Meaning 



Interest- 



Category 



GBLXCL'^ Declares global symbols to be H,M 

excluded from the .STB file 

LIBR Declares task's intention to access H,M 
a memory-resident shared region 

MAXBUF Declares an extension to the FORTRAN H 
record buffer 

ODTV Declares the address and size of M 

the debugging aid SST vector 

PAR Declares partition name and H,M 

dimensions 

PRI Declares priority H,M 

RESCOM Declare task's intention to access H,M 
RESLIB a memory-resident shared region 

RESSUp2 Declares task's intention to access a H,M 
resident suporvisor-mode library 

RQPAR? , ..Declares partition in which read-only H,M 
"/portion of multiuser task is to reside 

STACK Declares the size of the stack H,M 

SOPLLB'^- Declares task's intention to access a H,M 
system-owned supervisor-mode library 

TASK Declares the name of the task H,M 

TSKV Declares the address of the task M 

SST vector 

UIC Declares the user identification code H,M 
under which the task runs 

UNITS Declares the maximum number of units H,M 

VSECT Declares the virtual base address and H,M 
size of a program section 

WNDWS Declares the number of additional H,M 

address windows required by the task. 



alter 

share 

alloc 

synch 

ident 

ident 
share 

share 

ident 

alloc 
share 

ident 
synch 

ident 

device 
alloc 

alloc 



1. The user interest range is indicated as follows: 

• H indicates options of interest to high-level language (such 
as FORTRAN) programmers^ 

• M indicates options of interest to MACRO-11 programmers. 

2. These options are applicable to RSX-llM-PLUS systems only. 
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11.1.1 ABORT — Abort the Task-Build 

You use the ABORT option when you discover that an earlier error in 
the terminal sequence causes TKB to produce an unusable task image. 

The Task Builder, on recognizing the keyword ABORT, stops accepting 
input and restarts for another task build. 

Syntax 

ABORT=n 



An integer value. The integer is required to satisfy the general 
form of an option; however, the value is ignored in this case. 

Default 

None 



NOTE 

If you type a CTRL/Z at any time, it 
causes TKB to stop accepting input and 
begin building the task. 

The ABORT option is the only correct way 
for you to restart TKB if you discover 
an error and decide you do not want the 
Task Builder output. 
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11.1.2 ABSPAT — Absolute Patch 

You use the ABSPAT option to declare a series of object-level patches 
starting at a specified base address. You may use this option for 
conventional or I-and D-space tasks. IE use6.''_fo^--.^n^..^l-anA,'spr!'spap&. 
^f^s}c///^i/>& /option ^, Qatches I-space. See the DSPPAT option, 'you can 
specify up to eight patch values. 

Syntax 

ABSPAT=seg-name:address:vall:val2. . . :val8 
seg-name 

The 1- to 6-character Radix-50 name of the segment. 

address 

The octal address of the first patch. The address can be on a 
byte boundary; however, two bytes are always modified for each 
patch: the addressed byte and the following byte. 



vail 



An octal number in the range of through 177777 to be stored at 
address. 



val2 



An octal number in the range of through 177777 to be stored at 
address+2 



val8 



An octal number in the range of through 177777 to be stored at 
address+16. 



NOTE 

All patches must be within the segment 
address limits or TKB generates the 
following error message: 



TKB — *DIAG* — Load address out of range in module name 
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11.1.3 ACTFIL — Number of Active Files 

You use the ACTFIL option to declare the number of files that your 
task can have open simultaneously. For each active file that you 
specify, TKB allocates approximately 512 bytes. 

If you specify less than four active files (the default) , the ACTFIL 
option saves space. If you want your task to have more than four 
active files, you must use the ACTFIL option to make the additional 
allocation. 

You must include a language Object Time System (OTS) , such as FORTRAN, 
and record I/O service routines (FCS or RMS-11) in your task image for 
the extension to take place. The program section that is extended has 
the reserved name $$FSR1. 

Syntax 

ACTFIL=f ile-max 

f ile-max 

A decimal integer indicating the maximum number of files that can 
be open at the same time. 

Default 

ACTFIL=4 
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11.1.4 ASG — Device Assignment 

The ASG option declares the physical device that is assigned to one or 
more logical units. 

Syntax 

ASG=device-name:unit-numl:unit-num2. . . :unit-num8 

device-name 

A 2-character alphabetic device name followed by a 1- or 2-digit 
octal unit number. If your task uses more than six logical 
units, you must use the UNITS option to specify the number of 
logical units that your task will use. 

unit-numl 
unit-num2 



unit-num8 

Octal integers indicating the logical unit numbers, 
Default 

ASG=SY0:1:2:3:4,TI0:5,CL0:6 
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11.1.5 CLSTR — System-Owned Cluster of Resident Libraries or Commons 

The CLSTR option allows you to link your program to one to six shared 
regions, such as FMS, RMS, FORTRAN or BASIC+2, with a minimum of lost 
virtual address space for your task. CLSTR allows two to six shared 
regions in an RSX-llM system or an RSX-llM-PLUS system to reside in 
the same virtual address space in your task. 

You use CLSTR to declare a cluster or group of system-owned, resident 
libraries or commons that your task intends to access and have reside 
at the same virtual address in the address space of your task. 

The term "system-owned" means that TKB expects to find the commons or 
libraries named in the option and the symbol table associated with 
them under UFD [1,1] on device LB:. 

Syntax 

CLSTR=library_l,library_2, . . . library_n rswitch :apr 
library_n 

The library names must be 1- to 6- character Radix-50 names. TKB 
expects to find a symbol definition file of the same name for 
each specified shared region under UFD [1,1] on device LB:. The 
first specification denotes the first or the default library, 
which is the library to which the task is mapped when the task 
starts up and remaps after any call to another library. 

In an RSX-llM or „RS>fc-ll*In-.BLU& system, the total number of 
libraries to which a task may map is seven. The number of the 
component libraries in clusters is limited to a maximum of six. 
A cluster must contain a minimum of two libraries. It is 
possible to have two clusters of three libraries each or three 
clusters of two libraries each; any combination of number of 
clusters and libraries must equal at least two or a maximum of 
six. If six libraries are used in clusters, the task may map to 
only one other, separate library. 

:switch 

The switch :RW (read/write) or :R0 (read-only) indicates the type 
of access the task requires. All shared regions in the cluster 
have the same type of access. 



The apr is an integer in the range of 1 through 7 that specifies 
the first Active Page Register (APR) that you want TKB to reserve 
for the cluster of shared regions. You can specify it for a 
cluster made up of only position-independent shared regions. If 
you omit the APR parameter and all shared regions are position 
independent, TKB selects the highest available APR to map the 
cluster. A cluster can be made up of both position-independent 
and absolute shared regions. If one absolute shared region is 
present with position-independent shared regions, the 
position-independent shared regions assume the same base address 
as that of the absolute shared region. However, if you specify 
more than one absolute shared region, all must be built with the 
same base address. 
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Default 

None 



NOTE 

All but the first shared region in a 
cluster must be memory-resident overlaid 
libraries. The first shared region 
specified in the cluster option can be a 
single-segment structure (nonoverlaid) 
or an overlaid library. 
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11.1.6 CMPRT — Completion Routine — RSX-llM-PLUS Only 

The CMPRT option is available on RSX-llM-PLUS systems only. You use 
this option to identify a shared region as a supervisor-raode library. 
The CMPRT option requires an argument that specifies the entry point 
of the completion routine in the library. The completion routine 
switches the processor from supervisor to user mode and returns 
program control to the user task after the supervisor-mode library 
subroutine that was called from the user task has executed. 

Two completion routines are available in SYSLIB: 

• $CMPCS restores only the carry bit in the user-mode PS. 

• $CMPAL restores all the condition code bits in the user-mode- 
PS. 

These routines perform all the necessary overhead to switch the 
processor from supervisor to user mode and return program control to 
the user task at the instruction following the call to -a 
supervisor-mode library subroutine. 

Although you can write your own completion routines, it is best to use 
either $CMPCS or $CMPAL whenever possible. Chapter 8 discusses 
completion routines in detail. 

Syntax 

CMPRT=name 



name 



A 1- to 6-character Radix-50 name identifying the completion 
routine. 



Default 

None 
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11.1.7 COMMON or LIBR — System- Owned Resident Common or System-Owned 
Resident Library 

The COMMON and LIBR options are functionally identical; they both 
declare that your task intends to access a system-owned shared region. 
However, by convention, the COMMON option identifies a shared region 
that contains only data, and the LIBR option identifies a shared 
region that contains only code. 

If you use the COMMON option with an I- and D-space task, the common 
is mapped with D-space APRs only and therefore must contain data only. 

If you use the LIBR option with an I- and D-space task, the library is 
overmapped with both I-space and D-space APRs. 

The term "system-owned" means that TKB expects to find the common or 
library named in the keyword and the symbol definition file associated 
with it under UFD [1,1] on device LB:. 

Syntax 

COMMON=name : access-code [ : apr ] 

or 
LIBR=name: access-code [ :apr ] 



name 



The 1- to 6-character Radix-50 name specifying the common or 

library. TKB expects to find a symbol definition file having the 

same name as that of the common or library with an extension of 
.STB under [1,1] of device LB:. 



access-code 



The code RW (read/write) or the code RO (read-only) indicating 
the type of access the task requires. 



NOTE 

A privileged task can change data in or move data to a 
resident common even though the task has been linked to 
the common with read-only access. 
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apr 



An integer in the range of 1 through 7 that specifies the first 
Active Page Register (APR) that you want TKB to reserve for the 
shared region. TKB recognizes the APR only for a mapped system; 
you can specify it only for position-independent shared regions. 
If you omit the APR parameter and the shared region is position 
independent, TKB selects the highest available APR to map the 
region. 

When a shared region is absolute, the base address of the 
region — and therefore the APR that maps it — is determined by 
the arguments in the PAR option when the region is built. Refer 
to PAR in Section 11.1.18. 



Default 

None 
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11.1.8 DSPPAT — Absolute Patch for D-space 

You use the DSPPAT option to declare a series of object-level patches 
starting at the specified base address. Th,is option, is- for' making" 
patplres -to- the- D-space ofafl 'I- -^0*^ C-spatfe-task-. You may also use 
this option to patch a conventional task at any location. You can 
specify up to eight patch values. 

Syntax 

DSPPAT=seq-name:address :vall:val2 : . . . :val8 
segname 

The 1- to 6-character Radix-50 name of the segment. 

address 

The octal address of the first patch. The address can be on a 
byte boundary; however, two bytes are always modified for each 
patch: the addressed byte and the following byte. 



vail 



An octal number in the range of through 177777 to be stored at 
address. 



val2 



An octal number in the range of through 177777 to be stored at 
address+2. 



val8 



an octal number in the range Of through 177777 to be stored at 
address+16. 



NOTE 

All patches must be within the segment address limits or 
TKB generates the following error message: 



TKB — *DIAG* — Load address out of range in module-name 
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11.1.9 EXTSCT — Program Section Extension 

You use the EXTSCT option to extend a program section. 

If the program section to be extended has the attribute CON 

(concatenated) , TKB extends the section by the number of bytes you 

specify in the EXTSCT option. If the program section has the 

attribute OVR (overlay) , TKB extends the section only if the length 

you specify in the EXTSCT option is greater than the length of the 
program section. 

Syntax 

EXTSCT=p-sect-name:extension 

p-sect-name 

A 1- to 6-character radix-50 name specifying the program section 
to be extended. 

extension 

An octal integer that specifies the number of bytes by which to 
extend the program section. 

Example 

In the following example, the program section BUFF is 200 bytes 
long. 

EXTSCT=BUFF:250 

The number of bytes by which TKB extends the program section BUFF 
depends on the CON/OVR attribute: 

• For CON, the extension is 250 bytes. 

• For OVR, the extension is 50 bytes. 

TKB extends the program section if it encounters the program 
section name in an input object file or in the overlay 
description file. 

Default 
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11.1.10 EXTTSK — Extend Task Memory 

The EXTTSK option directs the system to allocate additional memory for 
your task when it is installed in a system-controlled partition. 

The amount of memory that the system allocates for your task is the 
su;n of the tusk size plus the increment you specify (rounded up to the 
nearest 32-word boundary). IC the task is built for a user-controlled 
partition, the allocation of task memory reverts to the partition 
size . 

This option extends only the D- space of an ]- and n-spaco task. 

In an unmapped system, TKB ignores the EXTTSK keyword. 

NOTES 



1. YOU should not use the EXTTSK option 
to extend a t.isk containing 
memory-resident overlays because the 
system does not map the extended 
area. 

2. When you use the EXTTSK option to 
extend a checkpointable task that 
has been declared checkpointable 
with the /AL switch, the check point 
file within the task image is the 
size of the task plus the size of 
the extended task area. 

3. Be careful when extending an I- and 
D-space task that is linked to a 
library which contains both data and 
instructions. Normally, libraries 
are mapped in both I-space and 
D-space allowing data and 
instructions to be intermixed. The 
extension length must not extend 
into the area maooed for the librg-rv 

/ - -or '- the-.'/ 1 ibr a r y ' will * be.: mapped' i Fi- 
■\- -■■■;■ I-space- -only-. , ■.■■:',/. „---/\ ./ 



Syntax, 

EXTTSK=length 

length 

A decimal riuraber in the range 0<n<65,535. specifying the 
increase in task memory allocation (in words). 



usi-ixuxx:. 



The task is extended to the size specified in the PAR option (see 
Section 11.1.18) . 
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11.1.11 FMTBUF — Format Buffer Size 

The FMTBUF Option declares the length of the internal working storage 
that you want TKB to allocate within your task for compiling format 
specifications at run time. The length of this area must equal or 
exceed the number of bytes in the longest format string to be 
processed . 

Run-time compilation occurs whenever an array is referred to as the 
source of formatting information within a FORTRAN I/O statement. The 
program section that TKB extends has the reserved name $$0BF1. 

Syntax 

FMTBUF=max- format 

max-format 

A decimal integer, larger than the default, that specifies the 
number of characters in the longest format specification. 

Default 

FMTBUF=132 
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11.1.12 GBLDEF — Global Symbol Definition 

You use the GBLDEF option to declare the definition of a global 
symbol. 

TKB considers this symbol definition to be absolute. It overrides any 
definition in your input object modules. 

Syntax 

GBLDEF=symbol-name: symbol-value 
symbol-name 

A 1- to 6-character Radix-50 name of the defined symbol. 

symbol -value 

An octal number in the range of through 177777 assigned to the 
defined symbol. 

Default 

None 



11-17 



OPTIONS 



GBLINC 



11.1.13 GBLINC ~ Include Global Symbols 

The GBLINC option directs the Task Builder to include the symbol or 
symbols specified in this option in the .STB file being generated by 
the link operation in which this option appears. This option is 
intended for use when creating shared regions, in particular shared 
libraries, when you want to force particular modules to be linked to 
your task that references this library. The global symbol references 
specified by this option must be satisfied by some module or GBLDEF 
specification when you build the task. 

Syntax 

GBLINC=symbol-name, symbol-name, .... , symbol-name 

symbol-name 

The symbol to be included. 
Default 

None 
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11. 1.14 GBLPAT — Global Relative Patch 

The GBLPAT option declares a series of object-level patch values 
starting at an offset relative to a global symbol. You can specify up 
to eight patch values. 

Syntax 

GBLPAT=seg-nameJsym-name [+/-of f set] : vail :val2 . . . svalS 
seg-name 

The 1- to 6-character Radix-50 name of the segment, 
sym-name 

A 1- to 6-character Radix-50 name specifying the global symbol. 
offset 

An octal number specifying the offset from the global symbol. 

vail 

An octal number in the range of through 177777 to be stored at 
the octal address of the first patch. 



val2 



An octal number in the range of through 177777 to be stored at 
the first address+2. 



val8 



An octal number in the range of through 177777 to be stored at 
the first address+14. 



Default 

None 



NOTE 

All patches must be within the segment 
address limits or TKB generates a fatal 
error . 
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11.1.15 GBLREF — Global Symbol Reference 

The GBLREF option declares a global symbol reference. The reference 
originates in the root segment of the task. This keyword is used for 
memory-resident overlays of shared regions. 

Syntax 

GBLREF=symbol-name, symbol-name. . . , symbol-name 
symbol-name 

A 1- to 6-character name of a global symbol reference. 
Default 

None 
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11.1.16 GBLXCL — Exclude Global Symbols 

The GBLXCL option keyword directs TKB to exclude from the symbol 
definition file of a shared region the symbol (s) specified in the 

option. 

Syntax 

GBLXCL=symbol-name, symbol-name. . . , symbol-name 
symbol -name 

The symbol (s) to be excluded. 
Default 

None 
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11.1.17 LIBR — System-Owned Library 
Refer to COMMON in Section 11.1.7. 
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11.1.18 MAXBOF — Maximum Record Buffer Size 

The MAXBUF option declares the maximum record buffer size required for 
any file used by the task. 

If your task requires a maximum record size that exceeds the default 
buffer length, you must use this option to extend the buffer. 

You must also include a language Object Time System (GTS) , such as 
FORTRAN, in your task image for the extension to take place. The 
program section that is extended has the reserved name $$1031. 

Syntax 

MAXBUF=max-record 

max-record 

A decimal integer, larger than the default, that specifies the 
maximum record size in bytes. 

Default 

MAXBUF=133 
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11.1.19 ODTV — DDT SST Vector 

The ODTV option declares that a global symbol is the address of the 
ODT Synchronous System Trap vector. You must define the global symbol 
in the main root segment of your task. 

Syntax 

ODTV=symbol-name: vector-length 
symbol -name 

A 1- to 6-character Radix-50 name of a global symbol. 

vector-length 

A decimal integer in the range of 1 through 32 specifying the 
length of the SST vector in words. 

Default 

None 
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11.1.20 PAR — Partition 

The PAR option identifies the partition for which your task is built. 

In a mapped system, you can install your task in any system partition 
or user partition large enough to contain it. In an unmapped system, 
your task is bound to physical memory. Therefore, you must install 
your task in a partition starting at the same memory address as that 
of the partition for which it was built. 

Syntax 

PAR=pname [ :base : length] 
pname 

The name of the partition. 

base 

The octal byte address defining the start of the partition. On 
an unmapped system, the physical address must be specified. On a 
mapped system, the base must be for a task or a 4K boundary for 
a shared region. 

length 

The octal number of bytes contained in the partition. 

In a mapped system, a length of implies a system-controlled 
partition. 

If the target system is mapped and you specify a partition length 
that is greater than the length of your task, the Task Builder 
automatically extends the length of your task to match the length 
of the partition. This procedure is equivalent to using the 
EXTTSK keyword to increase the task memory. If your task size is 
greater than the partition size that you specify, TKB generates 
the following error message: 

TKB — *DIAG*-Task has illegal memory limits 

Whether or not the target system is mapped, the Task Builder does 
not extend the length of a shared region, or any task built 
without a header, to match the specified partition length. 

If you do not specify the base and length, TKB tries to obtain that 
information from the system on which you are building your task. If 
you have specified a partition that resides in that system, TKB can 
obtain the base and length. 
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TKB binds the task to the addresses defined by the partition base. If 
the partition is user controlled, TKB verifies that the task does not 
exceed the length specification. 

On RSX-llM-PLUS, a TKB command sequence or build file £or a 
memory-resident overlaid library must contain the statement PAR=xxx, 
where xxx is the same name as that of the region being built. 

Default 

PAR=GEN 
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11.1.21 PRI — Priority 

The PRI option declares your task's execution priority. 

On systems with multiuser protection, you cannot run a task at a 
priority that is greater than the system priority (50) unless it is 
installed or run from a privileged terminal. If you are working from 
a privileged terminal, and you do not override this option by 
specifying a different priority when you install your task, the system 
uses this priority. 

Syntax 

PRI=priority-number 
priority-number 

A decimal integer in the range of 1 through 250 

Default 

Established by Install; refer to the RSX-llM/M-PLUS MCR 
Operations Reference Manual . 
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11.1.22 RESCOM or RESLIB — Resident Common or Resident Library 

The RESCOM and RESLIB options are functionally identical; they both 
declare that your task intends to access a user-owned, shared region. 
However, by convention the RESCOM option identifies a shared region 
that contains only data and the RESLIB option identifies a shared 
region that contains only code. 

If you use the RESCOM option with an I- and D-space task, the common 
is mapped with D-space APRs only and therefore must contain data only. 

If you use the RESLIB option with an T- and D-space task, the library 
is overmapped with both I-space and D-spaco APRs. 

The term "user-owned" means that the resident common or library and 
the symbol definition file associated with it can reside under any UFO 
that you choose. You can specify the UFD and remaining portions of 
the file specification for both options. You must not place comments 
on the same line with either option. 

Syntax 

RESCOM=f ile-specif ication/access-code [ :apr] 

or 

RESLIB=f ile-specif ication/access-code [ :apr] 

file-specification 

The memory image file of the resident common or resident library. 
The file specification format is discussed in Chapter 1. 

access-code 

The code RW (read/write) or the code RO (read-only) , indicating 
the type of access required by the task. 

NOTE 

A privileged task can change data in or move data into a 
resident common even though the task has been linked to 
the common with read-only access. 



apr 



An integer in the range of 1 through 7 that specifies the first 
Active Page Register (APR) that you want TKB to reserve for the 
common or library. TKB recognizes the APR argument only for a 
mapped system. You can specify it only for position-independent 
shared regions. If the APR parameter is omitted and the shared 
region is position independent, TKB selects the highest available 
APR to map the region. 

When a shared region is absolute, the base address of the 
region — and therefore the APR that maps it — is determined by 
the arguments in the PAR option when the region is built. Refer 
to PAR in Section 11.1.18. 
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OPTIONS 



RESCOM or RESLIB (Cont.) 



NOTES 



1. The Task Builder expects to find a symbol definition 
file having the same name as that of the memory image 
file but with a file type of .STB, on the same device 
and under the same UFD as that of the memory image 
file. 

2. Regardless of the version number you give in the file 
specification, TKB uses the latest version of the 

.STB file. 



Default 



When you omit portions of the file-specification, the following 
defaults apply: 

• UFD - Taken from current terminal UIC 

• Device - SYO: 

• File type - .TSK 

• File version - Latest 
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RESLIB 

11.1.23 RESLIB — Resident Library 

Refer to RESCOM in Section 11.1.21. 
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OPTIONS 



RESSUP 



11.1.24 RESSUP — Resident Supervisor^Mpde Library ~ RSX-lIM- PLUS only 

The RESSUP option declares tHat your task intends; to .aiqcess. /^^a 
user-owned, supervisor-mode library, /The term "user-owned" means that .;■ 
the library and the symbol definitiojri file .associated with . it, can 
reside under any UKD that ypw choose. -You c,^a specify 'the OT^ 
remaining portions oT the file specification^ ■ You; m^^ 
comments on the line with RESSUP, ■ ,/; ,,,;,.: 

Syntax -''■V;^:^ ■■'■■-■■ ■'■ '/•■-':■--■''■ .y^.^- ■.''-■ '~V :■'■.■': ■'^i^-^ \y 

RESSUP=file-speciCication/[:^].;SSFt:ap,r] ■•■-■/' ''^;'V/ -V^'V-'/- ■ ;' ■^'■'-'v-'- "^^^ 

file-specification '"'>-■';■ V-'';-' ■•■'■ ''-y ■■.■'/'•''■'/'.■ ''-'r.'/:-''.- '■:'.' '.:■'/■■'''/: yVi-^V'A 

The memory image file of the ^Mopervi s6r-tno(fe* 1 iHracy . ,/ * / 

specification has the 'strarndeir^': RS)S-ril^RSX-^^ 

discussed in Chapter 1. ,1, '/ ^I 1,., :.'■.."-.'' ^J .'... 



/[-]SV 



apr 



The code /SV or /-SV tb V indiceit^ " >a^ 

mode-switching vectors withikv-the ^iSer/^tastev'-yJ /^''.' 

TKB includes a 4-word, modeVswitching;vectqr within the /ad^^ 

space of the user task for each call to a supervisor-modW library 

subroutine. If you specify ;/-SV.,.r you. -muat, provide ,,yoai.j o.wA' 

mode-switching vector. Providing your' own mOde-switcHing vectors: 

is useful if your library con-tains -tJhr^adedjCiide^iv ^^ 

use the system-supplied vectors "whenever possible, ,: - ," 



An integer in the range of;p,:l;hj;oAigfa.-'7/;tha.t'v;3pe'cif leTs^^ 

Supervisor Active Page Reglstet. that, ^au'vWa^ 

your supervisor-mode libr^y,;^; /Y©u;<;an: ispe;Gi..fyV:an / APS; -^ 

posit ion- independent , supervl^or^iiiQde -llbrar'^^ 

the lowest available APR. ^-.-'v'.'';;"--?. .';;;.';■ ' '^■.■'S'yy ■:.' ■.. y//: /.'..-"-y'- ■-'.':' ■ 

The library at virtual nfait';ha've the ,CSf?;<JispatC^ 

the sys tem-suppl i ed completion r patitie 4escr it)ed in- ,<ih^p1;er/ .8^-, ;/; 

■■■'■''. -NiOTEs' ■■■^- "-■■;■■'■■■■'■■"■■' '■■^--'r-" ■'^;;>' 



The Task Builder expects to-firid a;symhol definition 
file having the Same name as that of the memory image 
file but with a file type of ,STB, on the same device 
and under the same UFD as that of the memory image 
file. .' 

Regardless of the version number you give in the file 
specification, TKB uses the latest version of the 



. O'l 



B 
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OPTIONS 



RESSUP (Cont.) 



Default 



When you o;riit portions oE t'ne file spcci Eication , the following 
defaults 'ipply: 

• 'JFD - Taken from the current terminal tJIC 

• Device - SYO: 

• File typo - .TSK 

• File version - Latest 
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OPTIONS 



ROPAR 



11.1.25 ROPAR — Read-only Partition — RSX-llM-PLDS Only 

You use this option to declare the partition in which the read-only 
portion oC your multiuser task is to reside. 

Syntax 

ROPAR=parnamo 
parname 

The partition name in which your muitiuser task is to reside. 
Default 

The partition in which the read/write portion of the task 
resides. 
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OPTIONS 



STACK 



11.1.26 STACK — Stack Si^e 

The STACK option declares the maximum size of the stack required by 
your task. 

The stack is an area of memory that the MACRO-11 programmer uses for 
temporary storage, subroutine calls, and synchronous trap service 
linkage. The stack is referred to by hardware register 6 (SP, the 
stack pointer) . 

Syntax 

STACK=stack-size 

stack-size 

A decimal integer specifying the number of words required for the 
stack. 

Default 

STACK=256 
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OPTIONS 



SUPLIB 



11.1.27 SOPLIB — Supervisor-Mode Library — RSX-llM-PLOS Only 

This option declares that yoiar task intends to access a system-owned, 
supervisbr-mode library. The term "system-owned" means that TKB 
expects to find the supervisor-mode library and the symbol definition 
file associated with it in UFD [1,1] on device LB:. 

Syntax' .■'.■..' 

*. SUPLIB=name: [-]SV[:apr] 

name'; /. ■ ■, "" . . - ■■■ - ; ■ ■ 

S -V'The 1- to 6-charac_ter Radix-SO. riame specifying the system-owned > 
- . " - ■ .supervisor-mode library ; TKB' expects, to find a symbol, def i-nition 
.' . ;frle.:;having,-. the same name as that, of .the library with a' file 
"/•'. version of .STB under [1,1;] of device LB:.. 

H-lST; ■ ; .- ■ ; 

.. -The. code . /SV or - /-SV to. indicate whether TKB includes 

■ ■mode-switching vectors within the user task. If you specify /SV, 

.-TKB. includes a 4.-wbrd. mode-switching vector within the address 

space of the user task for each call to a supervisor-mode library 

'subroutine. If you specify /-SV, you must provide your own mode- 

. switching vector. Providing your own mode-switching vectors is 

useful if your library contains threaded code. It is best to use 

- the system- supplied vectors whenever possible. 



apt 



An integer in the range of through 7 that specifies the first 
Supervisor Active . Page Register that TKB is to reserve for the 
Library, You, can specify an APR only for .position-independent, 
supervisor-mode libraries. The default is the lowest available 

.APR-.-: '-■•■■■■' 

The library at virtual must have the CSM dispatcher present in 
the system-supplied completion routine described in Chapter 8. 



Default 

None 
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TASK 



11.1.28 TASK — Task Name 

The TASK option gives your task an installed name different from its 
task image name. 

Syntax 

TASK=task-name 
task-name 

A 1- to 6-character name identifying your task. 
Default 

The first six characters of the task image file name identify the 
task when the task is installed. 
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OPTIONS 



TSKV 



11.1.29 TSKV — Task SST Vector 

The TSKV option declares that a global symbol is the address of the 
task Synchronous System Trap (SST> vector. You must define the global 
symbol in the main root segment of your task. 

Syntax 

TSKV=symbol-name: vector- length 
symbol-name 

A 1- to 6-character nam.e of a global symbol. 

vector-length 

A decimal integer in the range of 1 through 32 specifying the 
length of the SST vector in words. 

Default 

None 
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OPTIONS 



UIC 



11.1.30 OIC — Oser Identification Code 

The UIC option declares the User Identification Code (UIC) for your 
task when you run it with a time-based schedule request. 

Syntax 

UIC= [group , member ] 

group 

An octal number in the range of 1 through 377, or a decimal 
number in the range of 1 through 255. Decimal numbers must be 
followed by a decimal point (.). 



member 



An octal number in the range of 1 through 377, or a decimal 
number in the range of 1 through 255. Decimal numbers must be 
followed by a decimal point (.). 



Default 



The UIC that the Task Builder is running under (normally the 
terminal UIC) . 
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OPTIONS 



UNITS 



11.1.31 UNITS — Logical Unit Osage 

The UNITS option declares the number of logical units that your task 
uses. 

Syntax 

UNITS=inax-units 
max-units 

A decimal integer in the range of through 250 specifying the 
maximum number of logical units. A 2-word block is allocated in 
the task's header for every logical unit. A task that uses many 
logical units can use a significant portion of dynamic memory 
because the header is in dynamic memory when the task is 
executing. The /XH switch affects pool usage by the task header. 

Default 

UNITS=6 
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OPTIONS 



VSECT 



11,1.32 VSECT — Virtual Program Section 

The VSECT option specifies the virtual base address, virtual length, 

and, optionally, the physical memory allocated to the named program 

section. Refer to Chapter 5 for more information on virtual program 
sections . 

Syntax 

VSECT=p-sect-name:base: window [ :physical-length] 
p-sect-name 

A 1- to 6-character program section name. 



base 



An octal value representing the virtual base address of the 

program section in the range of through 177777. If you use the 

mapping directives, the value you specify must be a multiple of 
4K. 

window 

An octal value specifying the amount of virtual address space in 
bytes allocated to the program section. Base plus window must 
not exceed 177777 (octal). 

physical-length 

An octal value specifying the minimum amount of physical memory 
to be allocated to the section in units of 64-byte blocks. TKB 
rounds this value up to the next 256-word limit. This value, 
when added to the task image size and any previous allocation, 
must not cause the total to exceed 2048K bytes. If you do not 
specify a length, TKB assumes a value of 0. 

Default 

Physical-length defaults to 0. 
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WNDWS 



11.1.33 WNDWS — Number of Address Windows 

The WNDWS option declares the number of address windows required by 
the task in addition to those needed to map the task image, and any 
mapped array or shared region. The number specified is equal to the 
number of simultaneously mapped regions the task will use. 

Syntax 

WNDWS =n 



An integer in the range 1 through 7 in an, ESX-llM, system and 
through 23 in an RSX-llM-PLUS system. 

Default 

WNDWS =0 
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APPENDIX A 
TASK BUILDER INPOT DATA FORMATS 



An Object module is the fundamental unit of input to the Task Builder 
(TKB) . You create an object module by using any of the standard 
language processors (for example, MACRO-11 or FORTRAN) or by using TKB 
itself (symbol definition file). The RSX-llM/M-PLUS librarian (LBR) 
gives you the capability to combine a number of object modules into a 
single library file. 

An object module consists of variable-length records of information 
that describe the contents of the module. These records guide TKB in 
translating the object language into a task image. Six record (block) 
types are included in the object language: 

• Declare global symbol directory (GSD) record (type 1) 

• End of global symbol directory (GSD) record (type 2) 

• Text information (TXT) record (type 3) 

• Relocation directory (RLD) record (type 4) 

• Internal symbol directory (ISD) record (type 5) 

• End-of-module record (type 6) 

TKB requires at least five of these record types in each object 
module. The only record type that it does not require is the internal 
symbol directory. 

The various record types are defined according to a prescribed format, 
as illustrated in Figure A-1. An object module must begin with a 
declare-GSD record and end with an end-of-module record. Additional 
declare-GSD records can occur anywhere in the file, but must occur 
before an end-of-GSD record. An end-of-GSD record must appear before 
the end-of-module record, and at least one RLD record must appear 
before the first TXT record. Additional RLD and TXT records can 
appear anywhere in the file. The ISD records can appear anywhere in 
the file between the initial declare-GSD record and the end-of-module 
record. 

Object module records are variable length and are identified by a 
record type code in the first byte of the record. The format of 
additional information in the record depends on the record type. 
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The following sections describe each of the six record types in 
greater detail. The outline of these sections is as follows: 

A,l Declare Global Symbol Directory Record 

A. 1.1 Module Name (Type 0) 

A. 1.2 Control Section Name (Type 1) 

A. 1.3 Internal Symbol Name (Type 2) 

A. 1.4 Transfer Address (Type 3) 

A. 1.5 Global Symbol Name (Type 4) 

A. 1.6 Program Section Name (Type 5) 

A. 1.7 Program Version Identification (Type 6) 

A. 1.8 Mapped Array Declaration (Type 7) 

A. 1.9 Completion Routine Name (Type 10) 

A. 2 End of Global Symbol Directory Record 

A. 3 Text Information Record 

A. 4 Relocation Directory Record 

A. 4.1 Internal Relocation (Type 1) 

A. 4. 2 Global Relocation (Type 2) 

A. 4. 3 Internal Displaced Relocation (Type 3) 

A. 4. 4 Global Displaced Relocation (Type 4) 

A. 4. 5 Global Additive Relocation (Type 5) 

A. 4. 6 Global Additive Displaced Relocation (Type 6) 

A. 4. 7 Location Counter Definition (Type 7) 

A. 4.8 Location Counter Modification (Type 10) 

A. 4. 9 Program Limits (Type 11) 

A. 4. 10 Program Section Relocation (Type 12) 

A. 4. 11 Program Section Displaced Relocation (Type 14) 

A. 4. 12 Program Section Additive Relocation (Type 15) 

A. 4. 13 Program Section Additive Displaced Relocation 

Type 16) 

A. 4. 14 Complex Relocation (Type 17) 

A. 4. 15 Resident Library Relocation (Type 20) 

A. 5 Internal Symbol Directory Record 

A. 6 End of Module Record 



A.l DECLARE GLOBAL SYMBOL DIRECTORY RECORD 

The global symbol directory (GSD) record contains all the information 
required by TKB to assign addresses to global symbols and to allocate 
the virtual address space required by a task. 

GSD records are the only records processed by TKB in its first pass; 
therefore, you can save substantial time by placing all GSD records at 
the beginning of a module (because the Task Builder has to read less 
of the file) . 

GSD records contain nine types of entries: 

• Module name (type 0) 

• Control section name (type 1) 

• Internal symbol name (type 2) 

• Transfer address (type 3) 

• Global symbol name (type 4) 
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• Program section name (type 5) 

• Program version identification (type 6) 

• Mapped array declaration (type 7) 

• Completion routine name (type 10) 

TASK BUILDER DATA FORMATS 



GSD 



RLD 



GSD 



TXT 



TXT 



RLD 



Initial Declare GSD 

Initial Relocation Directory 

Additional GSD 

Text Information 

Text Information 

Relocation Directory 



GSD 



END GSD 



ISO 



ISD 



TXT 



TXT 



TXT 



END MODULE 



Additional GSD 
End of GSD 

Internal Symbol Directory 
Internal Symbol Directory 
Text Information 
Text Information 
Text Information 
End of Module 



Figure A-1 General Object Module Format 



Each entry type is represented by four words in the GSD record. As 
shown in Figure A-2, the first two words contain six Radix-50 
characters, the third word contains a flag byte and the entry type 
identification, and the fourth word contains additional information 
about the entry. 
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A. 1.1 Module Name (Type 0) 

The module name entry (two words) declares the name of the object 
module. The name need not be unique with respect to other object 
modules (that is, modules are identified by file, not module name), 
but only one such declaration can occur in any given object module. 
Figure A-3 illustrates the module entry name format. 






RECORD , 
TYPE 


RAD50 
NAME 


ENTRY TYPE 


FLAGS 


VALUE 


RAD50 
NAME 


TYPE 


... 
FLAGS 


VALUE 



RAD50 
NAME 


TYPE 


FLAGS 


VALUE 


RAD50 
NAME 


TYPE 


FLAGS 


VALUE 





Figure A-2 Global Symbol Directory Record Format 



MODULE 
NAME (2 WORDS) 


ENTRY 
TYPE 


= 









Figure A-3 Module Name Entry Format 
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A. 1.2 Control Section Name (Type 1) 

Control sections, which include absolute sections (ASECTs) , blank, and 
named control sections (CSECTs) , are replaced in RSX-llM by program 
sections (PSECTs) . For compatibility with other systems, TKB 
processes ASECTs and both forms of CSECTs. Section A. 1.6 details the 
entry generated for a .PSECT directive. 

ASECTs and CSECTs are defined in terms of .PSECT directives, as 
follows : 

For a blank CSECT, a program section is defined with the following 
attributes : 

.PSECT ,LCL,REL,CON,RW,I,LOW 
For a named CSECT, the program section is defined as: 

•PSECT name, GBL,REL,OVR,RW, I ,LOW 
For an ASECT, the program section is defined as: 

.PSECT . ABS. ,GBL,ABS,I,OVR,RW,LOW 

TKB processes ASECTs and CSECTs as program sections with the fixed 
attributes defined above. Figure A-4 illustrates the control section 
entry name format. 



CONTROL SECTION 
NAME (2 WORDS) 



ENTRY 
TYPE 



IGNORED 



MAXIMUM LENGTH 



Figure A-4 Control Section Name Entry Format 



A. 1.3 Internal Symbol Name (Type 2) 

The internal symbol name entry (two words) declares the name of an 
internal symbol (with respect to the module) . TKB does not support 
internal symbol tables; therefore, the detailed format of this entry 
is undefined. If TKB encounters an internal symbol entry while 
reading the GSD, it ignores that entry. Figure A-5 illustrates the 
internal symbol name entry format. 



SYMBOL 

NAME (2 WORDS) 


ENTRY 
TYPE 


= 2 





UNDEFINED 



Figure A-5 Internal Symbol Name Entry Format 
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A. 1.4 Transfer Address (Type 3) 

The transfer address entry declares the transfer address of a module 
relative to a program section. The first two words of the entry 
define the name of the program section, and the fourth word defines 
the relative offset from the beginning of that program section. If a 
transfer address is not declared in a module, then a transfer address 
must not be included in the GSD, or a transfer address of 000001 
relative to the default absolute program section (. ABS.) must be 
specified. Figure A-6 illustrates the transfer address entry format. 



NOTE 

If the program section is absolute, the 
offset is the actual transfer address 
(if not 000001) . 



SYMBOL 
NAME (2 WORDS) 



ENTRY 
TYPE 



= 3 



OFFSET 



Figure A-6 Transfer Address Entry Format 



A. 1.5 Global Symbol Name (Type 4) 

The global symbol name entry declares either a global reference or a 
definition. Definition entries must appear after the declaration of 
the program section in which the global symbols are defined and before 
the declaration of another program section (see Section A. 1.6). 
Global references can be used anywhere within the GSD. 

As shown in Figure A-7, the first two words of the entry define the 
name of the global symbol. The flag byte of the third word declares 
the attributes of the symbol, and the fourth word defines the value of 
the symbol relative to the program section in which the symbol is 
defined . 



SYMBOL 
NAME (2 WORDS) 


ENTRY 
TYPE 


= 4 


FLAGS 


VALUE 



Figure A-7 Global Symbol Name Entry Format 



Table A-1 lists the bit assignments of the flag 
declaration entry. 



byte of the symbol 
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Table A-1 
Symbol Declaration Flag Byte — Bit Assignments 



Bit Number and Name Setting 



Meaning 



Weak qualifier 



The symbol has a strong 
definition and is resolved in 
the normal manner. 

The symbol has a weak 
definition or reference. TKB 
ignores a weak reference (bit 
3=0). It also ignores a 
weak definition (bit 3=1) 
unless a previous reference 
has been made . 



Not used, 



Definition or 
reference type 



Definition 





1 



Normal definition or 
reference. 

Library definition. If the 
symbol is defined in a 
resident library STB file, the 
base address of the library is 
added to the value and the 
symbol is converted to 
absolute (bit 5 is reset) ; 
otherwise, the bit is ignored. 

Global symbol reference. 

Global symbol definition. 



Not used, 



Relocation 



Absolute symbol value. 
Relative symbol value. 



Not used, 



Not used . 



A. 1.6 Program Section Name (Type 5) 

The program section name entry declares the name of a program section 
and its maximum length in the module. It also uses the flag byte to 
declare the attributes of the program section. 



A- 7 



TASK BUILDER INPDT DATA FORMATS 



You must construct GSD records such that once a program section name 
has been declared, all global symbol definitions pertaining to it must 
appear before another program section name is declared. Global 
symbols are declared with symbol declaration entries. Thus, the 
normal format is a series of program section names each followed by 
optional symbol declarations. Figure A-8 illustrates the program 
section name entry format. 



PROGRAM SECTION 
NAME 



ENTRY 
TYPE 



= 5 



FLAGS 



MAXIMUM LENGTH 



Figure A-8 Program Section Name Entry Format 



Table A-2 lists the bit assignments of the flag byte of the program 
section name entry. 



Table A-2 
Program Section Name Flag Byte — Bit Assignments 



Bit Number and Name Setting 



Meaning 



Save 





1 



Normal program section. 

The program section is forced 
into the root of the task. 



Library program, 
section 



Normal program section. 



The program section is 
relocatable and refers to a 
shared region. 



Allocation 



Program section references are 
to be concatenated with other 
references to the same program 
section to form the total memory 
allocated to the section. 



Program section references are 
to be overlaid. The total 
memory allocated to the program 
section is the largest request 
made by individual references to 
the same program section. 

(continued on next page) 
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Table A-2 (Cont.) 
Program Section Name Flag Byte — Bit Assignments 



Bit Number and Name Setting 



Meaning 



Not used; reserved for future 
DIGITAL use. 



Access 



The program section has 
read/write access. 

The program section has 
read-only access. 



Relocation 



The program section is absolute 
and requires no relocation. 



Scope 



The 



program 



section 



is 



relocatable and references to 
the control section must have a 
relocation bias added before 
they become absolute. 

The scope of the program section 
is local. References to the 
same program section are 
collected only within the 
segment in which the program 
section is defined. 



The scope of the program section 



is global 

references 

section 

boundaries. 

determines 

storage is 



TKB 
to the 
across 
The Task 



collects 
program 
segment 
Builder 



the segment in which 
allocated for a 
global program section either by 
the first module that defines 
the program section on a path, 
or by direct placement of a 
program section in a segment 
using the ODL .PSECT directive. 



Type 



The program section contains 
instruction (I) references. 



The program section 
data (D) references. 



contains 



NOTE 

The length of all absolute sections is 
0. 
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A. 1.7 Program Version Identification (Type 6) 

The program version identification entry declares the version of the 
module. TKB saves the version identification of the first module that 
defines a nonblank version. It then includes this identification on 
the memory allocation map and writes the identification in the label 
block of the task image file. 

The first two words of the entry contain the version identification. 

The flag byte and fourth words are not used and contain no meaningful 

information. Figure A-9 illustrates the program version 
identification entry format. 







SYMBOL 






NAME 




ENTRY 
TYPE 


= 6 











Figure A-9 Program Version Identification Entry Format 



A. 1.8 Mapped Array Declaration (Type 7) 

The mapped array declaration entry allocates space within the mapped 
array area of task memory. The array name is added to the list of 
task program section names and may be referred to by subsequent RLD 
records. The length (in units of 64-byte blocks) is added to the 
task's mapped array allocation. The total memory allocated to each 
mapped array is rounded up to the nearest 512-byte boundary. The 
contents of the flag byte are reserved and assumed to be 0. 

One additional window block is allocated whenever a mapped array is 
declared. 

Figure A-10 illustrates the mapped array declaration entry format. 





MAPPED ARRAY 
NAME 








ENTRY 
TYPE 


= 7 


FLAGS 


LENGTH (NUMBER OF 64-BYTE BLOCKS) 



Figure A-10 Mapped Array Declaration Entry Format 
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A;ilv9 /Completion Routine Definition (Type IQ); ^ . 

The co'rapletion xoutine definition declares the .entry point for the 
completion /routine of a supervisor-mode library. This data structure 
i,s; created by the Task Builder and appears only in symbol definition 
files of supervisor-mode libraries. .'-■■■.. 

As shown ,in Figure a-11, the first two words of the' entry; define the. 
name of the entry- point. The third 'word contains the -entry type byte 
and the flag byte. The -flag byte contains no meaningful /infoimation . 
The ■fourth word contains the symbol value. ' ! 



COMPLETION ROUTINE 


NAME 


ENTRY _ ^„ 
TYPE 





VALUE 



Figure A-11 Completion Routine Entry' Fomat 



A. 2 END OF GLOBAL SYMBOL DIRECTORY RECORD 

The end of global symbol directory (end-of-GSD) record declares that 
no other GSD records are contained further on in the module. There 
must be exactly one end-of-GSD record in every object module. As 
shown in Figure A-12, this record is one word long. 






RECORD „ 
TYPE 



Figure A-12 End of Global Symbol Directory Record Format 



A. 3 TEXT INFORMATION RECORD 

The text information (TXT) record contains a byte string _ of 
information that is to be written directly into the task image file. 
The record consists of a load address followed by the byte string. 

TXT records can contain words and/or bytes of information whose final 
contents have not yet been determined. This information will be bound 
by a relocation directory record that immediately follows the text 
record (see Section A. 4) , If the TXT record needs no modification, 
then no relocation directory record is needed. Thus, multiple TXT 
records can appear in sequence before a relocation directory record. 

The load address of the TXT record is specified as an offset from the 
current program section base. At least one relocation directory 
record must precede the first TXT record. This directory must declare 
the current program section. 
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TKB writes a text record directly into the task image file and 
computes the value of the load address minus 4. This value is stored 
in anticipation of a subsequent relocation directory that modifies 
words and/or bytes contained in the TXT record. When added to a 
relocation directory displacement byte, this value yields the address 
of the word and/or byte to be modified in the task image. 

Figure A-13 illustrates the TXT record format. 






RECORD „ 
TYPE ■^ 


LOAD ADDRESS 


TE 


XT 


TEXT 




















• 
• 
• 






























' 






TEXT 


TEXT 



Figure A-13 Text Information Record Format 



information 
Every module 



A. 4 RELOCATION DIRECTORY RECORD 

The relocation directory (RLD) record contains the 

necessary to relocate and link the preceding TXT record. 

must have at least one RLD record that precedes the first TXT record 

The first RLD record does not modify a preceding TXT record; rather, 

it defines the current program section and location. RLD records 

contain 15 types of entries, classified as relocation or location 

modification entries: 



• Internal relocation (type 1) 

• Global relocation (type 2) 

• Internal displaced relocation (type 3) 

• Global displaced relocation (type 4) 



A-12 



TASK BOILDER INPUT DATA FORMATS 

• Global additive relocation (type 5) 

« Global additive displaced relocation (type 6) 

• Location counter definition (type 7) 

• Location counter modification (type 10) 

• Program limits (type 11) 

• Program section relocation (type 12) 

• Program section displaced relocation (type 14) 

• Program section additive relocation (type 15) 

• Program section additive displaced relocation (type 16) 

• Complex relocation (type 17) 

• Resident library relocation (type 20) 

Each type of entry is represented by a command byte that specifies the 
type of entry and the word/byte modification, followed by a 
displacement byte, and then by the information required for the 
particular type of entry. The displacement byte, when added to the 
value calculated from the load address of the preceding TXT record 
(see Section A. 3), yields the virtual address in the image that is to 
be modified. 

Table A-3 lists the bit assignments of the command byte of each RLD 
entry. 



Table A-3 
Relocation Directory Command Byte — 
Bit Assignments 



Bit Number and Name 



Setting 



Meaning 



0-6 Entry type 



Potentially, 128 command types 
can be specified; currently, 
15 are implemented. 



Modification 



The command modifies an entire 
word. 

The command modifies only one 
byte. TKB checks for 
truncation errors in byte 
modification commands. If 
truncation is detected (that 
is, if the modification value 
is greater than 255) , an error 
occurs. 



Figure A-14 illustrates the RLD record format. 



A-13 



TASK BOILDER INPOT DATA FORMATS 






RECORD . 
TYPE ^ 


DISP 


CMD 


INFO 

1 


INFO 










































V 


V 


T 

INFO 


INFO 



DISP 


CMD 


IN 


FO 


INFO 






























1 




IN 


FO 


IN 


FO 


DISP 


CMD 


INFO 


INFO 


] 


' 




f 


\ 
IN 


FO 


IN 


FO 



Figure A-14 Relocation Directory Record Format 



A. 4.1 Internal Relocation (Type 1) 



The internal relocation entry relocates a direct pointer to an address 
within a module. TKB adds the current program section base address to 
a specified constant, and writes the result into the task image file 
at the calculated address (that is, a displacement byte is added to 



the value calculated from the 
block) 



load address of the preceding text 
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For example: 

A: MOV #A,RO 
or 
.WORD A 
Figure A-15 illustrates the internal relocation entry format. 



DISP 


B 




ENTRY 
TYPE 


= 1 


CONSTANT 



Figure A-15 Internal Relocation Entry Format 

A. 4. 2 Global Relocation (Type 2) 

The global relocation entry relocates a direct pointer to a global 
symbol. TKB obtains the definition of the global symbol and writes 
the result into the task image file at the calculated address. 

For example: 

MOV #GLOBAL,R0 
or 

.WORD GLOBAL 
Figure A-16 illustrates the global relocation entry format. 



DISP 


B 




ENTRY 
TYPE 


= 2 


SYMBOL 
NAME 



Figure A-16 Global Relocation Entry Format 



A. 4. 3 Internal Displaced Relocation (Type 3) 

The internal displaced relocation entry relocates a relative reference 
to an absolute address from within a relocatable control section. TKB 
subtracts the address plus 2 that the relocated value is to be written 
into from the specified constant, and writes the result into the task 
image file at the calculated address. 

For example: 

CLR 177550 



or 



MOV 



177550, RO 
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Figure A-17 illustrates the internal displaced relocation entry 
format. 



DISP 


B 




ENTRY 
TYPE ' 


= 3 


CONSTANT 



Figure A-17 Internal Displaced Relocation Entry Format 



A. 4. 4 Global Displaced Relocation (Type 4) 

The global displaced relocation entry relocates a relative reference 
to a global symbol. TKB obtains the definition of the global symbol; 
subtracts the address plus 2 that the relocated value is to be written 
into from the definition value; and writes the result into the task 
image file at the calculated address. 

For example: 

CLR GLOBAL 
or 

MOV GLOBAL, RO 
Figure A-18 illustrates the global displaced relocation entry format. 



DISP 


B 




ENTRY 
TYPE 


= 4 


SYMBOL 
NAME 



ZK-461-S1 

Figure A-18 Global Displaced Relocation Entry Format 



A. 4. 5 Global Additive Relocation (Type 5) 

The global additive relocation entry relocates a direct pointer to a 
global symbol with an additive constant. TKB obtains the definition 
of the global symbol; adds the specified constant to the definition 
value; and writes the result into the task image file at the 
calculated address. 

For example: 

MOV #GLOBAL+2,R0 

or 



.WORD GLOBAL-4 
Figure A-19 illustrates the global additive relocation entry format. 
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DISP 


B 


ENTRY 
TYPE 


= 5 


SYMBOL 
NAME (2 WORDS) 


CONSTANT 



Figure A-19 Global Additive Relocation Entry Format 

A. 4. 6 Global Additive Displaced Relocation (Type 6) 

The global additive displaced relocation entry relocates a relative 
reference to a global symbol with an additive constant. TKB obtains 
the definition of the global symbol; adds the specified constant to 
the definition value; subtracts the address plus 2 that the relocated 
value is to be written into from the resultant additive value; and 
writes the result into the task image file at the calculated address. 

For example: 

CLR GLOBAL+2 



or 



MOV 



GLOBAL-5,R0 



Figure A-20 illustrates the global additive displaced relocation entry 
format. 



DISP 



ENTRY 
TYPE 



SYMBOL 
NAME (2 WORDS) 



CONSTANT 



Figure A-20 Global Additive Displaced Relocation Entry Format 



A. 4. 7 Location Counter Definition (Type 7) 

The location counter definition entry declares a current program 
section and location counter value. TKB stores the control base as 
the current control section; adds the current control section base to 
the specified constant; and stores the result as the current location 
counter value. 

Figure A-21 illustrates the location counter definition entry format. 
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ENTRY 
TYPE 



PROGRAM SECTION 
NAME (2 WORDS) 



CONSTANT 



Figure A-21 Location Counter Definition Entry Format 



A. 4. 8 Location Counter Modification (Type 10) 

The location counter modification entry modifies the current location 
counter. TKB adds the current program section base to the specified 
constant and stores the result as the current location counter. 

For example: 

. = .+N 

or 

.BLKB N 

Figure A-22 illustrates the location counter modification entry 
format. 






B 




ENTRY 
TYPE 


= 10 




CONSTANT 







Figure A-22 Location Counter Modification Entry Format 



A. 4. 9 Program Limits (Type 11) 

The program limits entry is generated by the .LIMIT assembler 
directive. TKB obtains the first address above the header (normally 
the beginning of the stack) and the highest address allocated to the 
task. It then writes these two addresses into the task image file at 
the calculated address and at the calculated address plus 2, 
respectively. 

For example: 

.LIMIT 

Figure A-23 illustrates the program limits entry format. 
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DISP 


B 


ENTRY 
TYPE ' ' 



Figure A-23 Program Limits Entry Format 



A. 4. 10 Program Section Relocation (Type 12) 

The program section relocation entry relocates a direct pointer to the 
beginning address of another program section (other than the program 
section in which the reference is made) within a module. TKB obtains 
the current base address of the specified program section and writes 
it into the task image file at the calculated address. 



For example; 



.PSECT A 



.PSECT C 
MOV #B,RO 

or 

.WORD B 

Figure A-24 illustrates the program section relocation entry format, 



DISP 


B 


ENTRY 
TYPE 


= 12 


PROGRAM SECTION 
NAME (2 WORDS) 



Figure A-24 Program Section Relocation Entry Format 



A. 4. 11 Program Section Displaced Relocation (Type 14) 

The program section displaced relocation entry relocates a relative 
reference to the beginning address of another program section within a 
module. TKB obtains the current base address of the specified program 
section; subtracts the address plus 2 that the relocated value is to 
be written into from the base value; and writes the result into the 
task image file at the calculated address. 
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.PSECT A 



.PSECT C 
MOV B,RO 



Figure A-25 illustrates the program section displaced relocation entry 
format . 



DISP 


B 


ENTRY 
TYPE ■ 


= 14 


PROGRAM SECTION 
NAME (2 WORDS) 



Figure A-25 Program Section Displaced Relocation Entry Format 



A. 4. 12 Program Section Additive Relocation (Type 15) 

The program section additive relocation entry relocates a direct 
pointer to an address in another program section within a module. TKB 
obtains the current base address of the specified program section; 
adds this address to the specified constant; and writes the result 
into the task image file at the calculated address. 



For example: 



, PSECT A 



.PSECT D 
MOV #B+10,R0 
MOV #C,RO 

or 

.WORD B+10 
.WORD C 

Figure A-26 illustrates the program section additive relocation entry 
format. 
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DISP 



ENTRY 

TYPE 



15 



PROGRAM SECTION 
NAME (2 WORDS) 



CONSTANT 



Figure A-26 Program Section Additive Relocation Entry Format 



A. 4. 13 Program Section Additive Displaced Relocation (Type 16) 

The program section additive displaced relocation entry relocates a 
relative reference to an address in another program section within a 
module. TKB obtains the current base address of the specified program 
section; adds this address to the specified constant; subtracts the 
address plus 2 that the relocated value is to be written into from the 
resultant additive value; and writes the result into the task image 
file at the calculated address. 



For example: 



B: 



.PSECT A 



,PSECT D 
MOV B+10,R0 
MOV C,RO 

Figure A-27 illustrates the program section 
relocation entry format. 



additive diplaced 



DISP 



ENTRY 
TYPE 



16 



PROGRAM SECTION 
NAME (2 WORDS) 



CONSTANT 



Figure A-27 Program Section Additive Displaced Relocation 

Entry Format 
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A. 4. 14 Complex Relocation (Type 17) 

The complex relocation entry resolves a complex relocation expression. 
Such an expression is one in which any of the MACRO-11 binary or unary 
operations are permitted with any type of argument, regardless of 
whether the argument is an unresolved global symbol; is relocatable 
to any program section base; is absolute; or is a complex 
relocatable subexpression. 

The RLD command word is followed by a string of numerically specified 
operation codes and arguments. The operation codes each occupy one 
byte. The entire RLD command must fit in a single record. The 
following 15 operation codes are defined: 

• No operation — Byte 

• Addition (+) — Byte 1 

• Subtraction {-) — Byte 2 

• Multiplication {*) — Byte 3 

• Division (/) — Byte 4 

• Logical AND (&) — Byte 5 

• Logical inclusive OR (!) — . Byte 6 

• Negation (-) — Byte 10 

• Complement ("C) — Byte 11 
Store result (command termination) — Byte 12 



• 



• Store result with displaced relocation (command 
termination) — Byte 13 

• Fetch global symbol — Byte 16 (It is followed by four bytes 
containing the symbol name in Radix-50 representation.) 

• Fetch _ relocatable value — Byte 17 (It is followed by one byte 
containing the program section number, and two bytes 
containing the offset within the program section.) 

• Fetch constant — Byte 20 (It is followed by two bytes 
containing the constant.) 

• Fetch resident library base address — Byte 21 (If the file is 
a resident library STB file, the library base address is 
obtained; otherwise, the base address of the task image is 
fetched.) 

The STORE commands indicate that the value is to be written into the 
task image file at the calculated address. 

All operands are evaluated as 16-bit signed quantities using two's 
complement arithmetic. The results are equivalent to expressions that 
the assembler evaluates internally. The following rules should be 
noted: 

1. An attempt to divide by yields a result. The Task 
Builder issues a nonfatal diagnostic error message. 
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2. All results are truncated from the left to fit into 16 bits. 
No diagnostic error message is issued if the number is too 
large. If the result modifies a byte, TKB checks for 
truncation errors as described in Section A. 4. 

3. All operations are performed on relocated (additive) or 
absolute 16-bit quantities. PC displacement is applied to 
the result only. 



For example: 



.PSECT ALPHA 



. PSECT BETA 



B: 



MOV #A+B-G1/G2&"C1771201G3>>,R1 
Figure A-28 illustrates the complex relocation entry format, 



DISP 


B 


ENTRY . 
TYPE 


17 


COMPLEX STRING 


12 



Figure A-28 Complex Relocation Entry Format 



A. 4. 15 Resident Library Relocation (Type 20) 

The library relocation entry relocates a direct pointer to an address 
within a resident library. 

If the current file is a resident library symbol definition file 
(STB) , TKB obtains the base address of the library; adds this address 
to the specified constant; and writes the result into the task image 
file at the calculated address. If the file is not associated with a 
resident library, TKB uses the task base address. 

Figure A-29 illustrates the library relocation entry format. 



DISP 


B 




ENTRY 
TYPE 


20 


CONSTANT 



Figure A-29 Resident Library Relocation Entry Format 
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A. 5 INTERNAL SYMBOL DIRECTORY RECORD 

Internal symbol directory (ISD) records have two purposes: 

1. To pass information to symbolic debuggers via the .STB file 

2. To create autoload vectors dynamically for the entry points 
of the library 

TBK looks for global symbol definitions in the input object modules 
and looks for ISD records if /DA is specified; otherwise TKB ignores 
the ISD records. Some ISD records require no relocation and TKB can 
copy them directly into the .STB file. Others will require 
modification; after being modified, they can be written to the .STB 
file. In addition, TBK may need to generate some ISD records of its 
own in the .STB file. 

Except for autoloadable library entry points, TBK puts ISD records 
into the .STB file only if the /DA switch is used in the TKB command 
line. When TKB outputs the .STB file, it writes three major types of 
ISD records: 

• Type 1 records, TKB generated ISDs. The form of these records 
is language independent. 

• Type 3 records, written for any type 2 records in an input 
object module. TKB does this after adding data and then 
changing the type to 3. Type 2 relocatable/relocated records 
are those that contain both language dependent and independent 
sections. Language processors generate these records and TKB 
modifies them. They contain information that can be used to 
find the absolute task image address of source program 
entities (variables, program statements, etc.) 

• Type 4 records, written to the .STB file without modification. 
Type 4 records are literal records that contain language 
dependent information. Apart from the first few bytes, TKB 
ignores the rest of the record. 

These record formats are described in the following sections. 



A. 5.1 Overall Record Format 

ISD records have the same basic structure as all object language 
records. Because of the variety of different types, the skeleton 
structure must include additional fields that are common to all ISD 
record types. The general format of all ISD records is shown in 
Figure A-30. 
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15 8 


7 


MUST BE 


RECORD TYPE = 5 


RESERVED (0) 


ISD RECORD TYPE 


RECORD TYPE DEPENDENT 



Figure A-30 General Format of All ISD Records 



ISD record types fall into general categories. The categories are: 

— Illegal. 

1 — TKB-generated. 

2 -- Compiler-generated relocatable. 

3 — Relocated (type 2 after TKB processing) . 

4-127 — not defined and reserved for future use. 

128-255 — literal records; the type code identifies the 
generating language processor and the internal structure. 



A. 5. 2 TKB Generated Records (Type 1) 

The content of this record type is a string of individual items, each 
with its own format. The items are either start-of-segment items, 
task identification items, or autoloadable entry point items. The TKB 
generated record is similar to the structure of an RLD or GSD record. 
The general format is shown in Figure A-31, 



15 


8 


7 





LENGTH (BYTES) 


ITEM TYPE 


CONTENT DEPENDS ON ITEM TYPE 



Figure A-31 General Format of a TKB Generated Record 



A, 5. 2.1 Start-of-Segment Item Type (1) - The format 
start-of-segment item type is shown in Figure A-32. 



of 



the 
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15 



8 7 



LENGTH = 8 



ITEM TYPE = 1 



SEGMENT NAME 



SEGMENT DESCRIPTOR ADDRESS 



Figure A-32 Format of TKB Generated Start-of-Segment Item (1) 



A. 5. 2. 2 Task Identification Item Type (2) - The task identification 
item type ensures that a .STB file and the task image being debugged 
were generated at the same time. Otherwise, symbols that are found 
may not correspond to the actual task. 

The task identification item type exists to make the correlation 
between the .STB file and its related task possible. The contents of 
this item type correspond exactly to the first ten words of an area in 
a task image file, which is in the TKB created PSECT called $$DBTS. 



The format of the task identification item type 
A-33. 



is shown in Figure 



15 


8 


7 







LENGTH = 22. 


ITEM TYPE = 


= 2 




EIGHT-WORD TIME STAMP^ 


TWO-WORD NUMBER^ 



1. Its form is that which is returned by RSX-11M/M-PLUS directive 
GTIMS. 

2. TKB generates this number as an additional check on correspond- 
ence. Currently always zero. 

ZK-1061-S2 

Figure A-33 Format of TKB Generated Task Identification Item (2) 



A. 5. 2. 3 Autoloadable Library Entry Point Item Type (3) - TKB outputs 
the autoloadable library entry point item into a .STB file when 
building overlaid resident libraries. The ISD record contains the 
needed information for TKB to dynamically generate autoload vectors 
for entry points in the library. Autoload vectors appear only for 
those entry points that are referenced by the task. Unlike the other 
item types, the autoloadable library entry point item is not for use 
by debuggers. 
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The format of the autoloadable entry point item is shown in Figure 
A-34. 



15 



8 7 



LENGTH = 12. 



ITEM TYPE = 3 



SYMBOL 
NAME 



FLAGS BYTE 



ENTRY POINT OFFSET FROM LIBRARY BASE 



SEGMENT DESCRIPTOR OFFSET IN $$SGD1 



ZK-1062-82 



Figure A-34 Format of an Autoloadable Library Entry Point Item (3) 



A. 5. 3 Relocatable/Relocated Records (Type 2) 

These records are the central part of TKB's involvement in debugger 
communication. Every item type in these records must be standardized, 
and only standard items can appear. The general format of 
relocatable/relocated records is the same as that shown in Figure 
A-30. 

A language processor outputs these record types as type 2. When^ TKB 
processes them, it changes the type to type 3. It also fills in or 
modifies some fields. In the descriptions of following item types, 
fields that are filled in by TKB are marked with an asterisk (*) . 
They should be left as zero in language processor output. 



A. 5. 3.1 Module Name Item Type (1) - A module name item should be the 

first ISD entry of each object module. A debugger can assume that all 

following ISD information up to the next module name item relates to 
this module. 

The language code is included so that a debugger for a specific 
language can determine whether to ignore a module if it is written for 
another language. The language code has the same range of values as 
that of a language-dependent ISD record (128-255) and has the same 
meaning. 

The format of the module name item type is shown in Figure A-35. 
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15 8 


7 


LENGTH 


ITEM TYPE = 1 


MUST BE 


LANGUAGE CODE 


MODULE NAME1 



1. A counted ASCII string of the required length. A counted ASCII 
string is a byte string in which the first byte indicates the number of 
bytes to follow. 



Figure A-35 Format of a Module Name Item Type (1) 



A. 5. 3. 2 Global Symbol Item Type (2) - One type 2 item must appear for 
each global symbol definition that the language processor wants the 
debugger to understand. It need not, however, include definitions 
generated for the language processor run-time system. 

The format of the global symbol item type is shown in Figure A-36. 



15 



8 7 



LENGTH 



ITEM TYPE = 2 



SYMBOL NAME 
(RADIX-50) 



VALUE* 



DESCRIPTOR ADDRESS FOR CONTAINING 
OVERLAY SEGMENT* 



MUST BE ZERO 



FLAGS 



FULL SYMBOL NAME' 



1. Counted ASCII string of the required length. A counted ASCII 
string Is a byte string in which the first byte indicates the number of 
bytes to follow. 

ZK-1053-82 

Figure A-36 Format of a Global Symbol Item Type (2) 
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A. 5. 3. 3 PSECT Item Type (3) 



concatenated PSECT has two base 



addresses: one for the whole PSECT, and another for the part of it 
that belongs to this module. It is the base address for the part that 
belongs to this module that may be used by a debugger to convert local 
symbol values to absolute addresses. 

The segment descriptor address is necessary because PSECTs may move to 
segments other than the one in which it was placed. This address is 
relevant to languages that provide semi-automatic overlay generation, 
like COBOL-11. This word may be zero if the PSECT has not moved to 
another segment . 

The flag word is a copy of the flag word built by TKB. It allows for 
identification of VSECTs. 

The full PSECT name may be needed for some languages. 

The format of a PSECT item type is shown in Figure A-37. 



15 







LENGTH 


ITEM TYPE = 3 


o^rr^T MAR'ii" 






BASE ADDRESS OF PSECT IN THIS SEGMENT* 


BASE ADDRESS OF PSECT FOR THIS MODULE* 


LENGTH OF PSECT FOR THIS MODULE* 


DESCRIPTOR ADDRESS FOR CONTAINING 
SEGMENT* 


FLAG WORD* 


FULL PSECT NAME^ 



1. A counted ASCII string of the required length. A counted ASCII 
string is a byte string in which the first byte indicates the number of 
bytes to follow. 

ZK-1054-82 

Figure A-37 Format of a PSECT Item Type (3) 



A. 5. 3. 4 Line-Number or PC Correlation Item Type (4) - This item 

provides the information needed to translate a source line number into 

a task image address, or a task image address into a source line 
number . 

The format of a line-number or PC correlation item type is shown in 
Figure A-38. 
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15 



8 7 



LENGTH 



ITEM TYPE = 4 



PSECT 
NAME 



START PC 



DESCRIPTOR ADDRESS OF CONTAINING OVERLAY SEGMENT* 



START PAGE NUMBER 



START LINE NUMBER 



STRING OF ONE-BYTE ITEMS 



1. Offset into PSECT in type 2 records; absolute address in type 3 records. 



Figure A-38 Format of a Line-Number or PC Correlation Item Type (4) 



A. 5. 3. 5 Internal Symbol Name Item Type (5) - The internal symbol name 
item allows for the fact that a name may have more than one associated 
address. For example, a COBOL variable may have three associated 
addresses: the address of the area that contains the data, the 
address of a CIS descriptor, and the address of a picture string. 

The internal symbol name item is shown in Figure A-39. 



A. 5. 4 Literal Records (Type 4) 

Literal records may take any form, but the two-byte header shown in 
Figure A-40 must be present. 



A. 6 END OF MODULE RECORD 

The end-of-module record declares the end of an object module. There 
must be exactly one end-of-module record in every object module. As 
shown in Figure A-41, this record is one word long. 
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15 



8 7 



LENGTH 



OFFSET TO NAME 



MUST BE ZERO 



ITEM TYPE = 5 



OFFSET TO DATA 



NUMBER OF ADDRESSES 



PSECT 
NAME 



TASK IMAGE ADDRESS/OFFSET 



SEGMENT DESCRIPTOR ADDRESS* 



PSECT 
NAME 



TASK IMAGE ADDRESS/OFFSET (1) 



SEGMENT DESCRIPTOR ADDRESS* 



LANGUAGE-DEPENDENT DATA 



SYMBOL NAME 2 



1. Modified by TKB 

2. A counted ASCII string of the required lengtli. A counted ASCII 
string is a byte string in which the first byte indicates the number of 
bytes to follow. 



Figure A-39 Format of an Internal Symbol Name Item Type (5) 
15 8 7 



RESERVED (0) 



ISD RECORD TYPE 4 



Figure A-40 Format of a Literal Record Type 
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RECORD 
TYPE ° 



Figure A-41 End-of-Module Record Format 
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Figures B-1 through B-4 illustrate how the Task Builder (TKB) records 
a task image on disk. As noted in the following sections, parts of 
the task disk image shown in these figures are optional and may not be 
recorded for every task image. 

The following sections, which provide detailed information on the task 
image file structure, are organized as follows: 

B.l Label Block Group 

B.2 Checkpoint Area 

B.3 Header 

B.3.1 Low-memory Context 

B.3. 2 Logical Unit Table Entry 

B.4 Task Image 

B,4.1 Autoload Vectors for Conventional Tasks 

B.4. 2 - Autoload Vectors^ .fcjr 'I-, and D-Space Tasks 

B.4. 3 Task-Resident Segment Descriptor 

B.4. 4 Window Descriptor 

B.4. 5 Region Descriptor 

B.4. 6 Supervisor-Mode Vector 



B.l LABEL BLOCK GROUP 

The label block group precedes the task on the disk and contains data 
that is needed by the system to install and load a task but need not 
reside in memory during task execution. This group consists of three 
parts: 

• Task and resident library data (label block 0) 

• Table of LUN assignments (label blocks 1 and 2) 

• The segment load list (label block 3) 

Table B-1 describes the task and resident library data. Figure B-5 
illustrates how TKB organizes this data in label block 0. The INSTALL 
processor verifies the task and resident library data when entering 
the tasks into the System Task Directory (STD) file. You can obtain 
the offsets shown in Figure B-5 by calling the LBLDF$ macro that 
resides in macro library LB: [1,1] EXEMC.MLB. 
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RELATIVE DISK BLOCK 



RELATIVE DISK BLOCK 2 



LABEL BLOCK — TASK AND 
RESIDENT LIBRARY DATA 



LABEL BLOCK 1 — TABLE OF 
LUN ASSIGNMENTS 



LABEL BLOCK 2 — TABLE OF 
LUN ASSIGNMENTS (OPTIONAL) 



CHECKPOINT AREA 
(OPTIONAL) 



TASK HEADER- 
FIXED PART 



TASK HEADER- 
VARIABLE PART 



ROOT SEGMENT 
TASK CODE AND DATA 



^ 



) LABEL BLOCK GROUP 



J 



HEADER 



TASK IMAGE 



Figure B-1 Image on Disk of Non-Overlaid Conventional Task 



RELATIVE DISK BLOCK 
RELATIVE DISK BLOCK 1 

RELATIVE DISK BLOCK 2 



OVERLAY DATA BASE ( 



LABEL BLOCK — TASK AND 
RESIDENT LIBRARY DATA 



LABEL BLOCK 1 — TABLE OF 
LUN ASSIGNMENTS 



LABEL BLOCK 2 — TABLE OF 
LUN ASSIGNMENTS (OPTIONAL) 



CHECKPOINT AREA 
(OPTIONAL) 



TASK HEADER- 
FIXED PART 



TASK HEADER- 
VARIABLE PART 



ROOT SEGMENT 



OVERLAY RUN-TIME 

SYSTEM ROUTINES IN 

ROOT FOR LIBRARY 



AUTOLOAD VECTORS 

REGION DESCRIPTORS 

SEGMENT DESCRIPTORS 

WINDOW DESCRIPTORS 



) LABEL BLOCK GROUP 



HEADER 



\ TASK IMAGE 



J 



Figure B-2 Image on Disk of Conventional Non-Overlaid Task 
Linked to Overlaid Library 
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RELATIVE DISK BLOCK 



RELATIVE DISK BLOCK 1 



RELATIVE DISK BLOCK 2 



RELATIVE DISK BLOCK 3 



OVERLAY DATA BASE < 



LABEL BLOCK — TASK AND 
RESIDENT LIBRARY DATA 



LABEL BLOCK 1 — TABLE OF 
LUN ASSIGNMENTS 



LABEL BLOCK 2 — TABLE OF 
LUN ASSIGNMENTS (OPTIONAL) 



LABEL BLOCK 3 — SEGMENT 
LOAD LIST (OPTIONAL) 



CHECKPOINT AREA 
(OPTIONAL) 



TASK HEADER- 
FIXED PART 



TASK HEADER- 
VARIABLE PART 



ROOT SEGMENT 



OVERLAY RUN-TIME 
SYSTEM ROUTINES IN ROOT 



AUTOLOAD VECTORS 

REGION DESCRIPTORS 

SEGMENT DESCRIPTORS 

WINDOW DESCRIPTORS 



OVERLAY SEGMENT 1 



AUTOLOAD VECTORS 



OVERLAY SEGMENT 2 



AUTOLOAD VECTORS 



OVERLAY SEGMENT N 
AUTOLOAD VECTORS 



> LABEL BLOCK GROUP 



HEADER 



> TASK IMAGE 



Figure B-3 Image on Disk of Conventional Overlaid Task 



B-3 



DETAILED TASK IMAGE FILE STRDCTORE 



RELATIVE DISK BLOCK 
RELATIVE DISK BLOCK 1 
RELATIVE DISK BLOCK 2 

RELATIVE DISK BLOCK 3 

r 



TASK IMAGE { 



LABEL BLOCK — TASK AND RESIDENT LIBRARY DATA 



LABEL BLOCK 1 — TABLE OF LUN ASSIGNMENTS 



LABEL BLOCK 2 — 
TABLE OF LUN ASSIGNMENTS (OPTIONAL) 



LABEL BLOCK 3 — SEGMENT LOAD LIST (OPTIONAL) 



CHECKPOINT AREA (OPTIONAL) 



TASK HEADER (UNUSED COPY) FIXED PART 
TASK HEADER (UNUSED COPY) VARIABLE PART 



TASK ROOT — INSTRUCTION SPACE 



AUTOLOAD VECTORS — l-SPACE PART 



TASK HEADER (USER'S COPY) FIXED PART 
TASK HEADER (USER'S COPY) VARIABLE PART 



TASK STACK AREA 



TASK ROOT — DATA SPACE 



AUTOLOAD VECTORS — D-SPACE PART 



REGION DESCRIPTORS 
SEGMENT DESCRIPTORS 



WINDOW DESCRIPTORS 



OVERLAY SEGMENT 1 — l-SPACE 
AUTOLOAD VECTORS — l-SPACE PART 



OVERLAY SEGMENT 1 — D-SPACE 
AUTOLOAD VECTORS - D-SPACE PART 



OVERLAY SEGMENT 2 — l-SPACE 
AUTOLOAD VECTORS — l-SPACE PART 



OVERLAY SEGMENT 2 — D-SPACE 
AUTOLOAD VECTORS — D-SPACE PART 



LABEL BLOCK GROUP 



> 



V TASK ROOT 
t l-SPACE PART 



TASK ROOT 
D-SPACE PART 



OVERLAY SEGMENT N — l-SPACE 
AUTOLOAD VECTORS — l-SPACE PART 



OVERLAY SEGMENT N — D-SPACE 
AUTOLOAD VECTORS — D-SPACE PART 



Fiijuit; B-4 Image on Disk of Overlaid T- and D-Space Task 

Table B-1 
Task and Resident Library Data 

Parameter Definition 

L$BTSK Task name consisting of two words in Radix-50 format. 
This parameter is set by the TASK keyword. 

L$BPAR Partition name consisting of two words in Radix-50 

format. This parameter is set by the PAR keyword. 

(continued on next page) 
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Table B-1 (Cont.) 
Task and Resident Library Data 



Parameter 



Definition 



L$BSA Starting address of task. Marks the lowest task virtual 
address. This parameter is set by the PAR keyword. 

L$BHGV Highest virtual address mapped by address window 0. 

L$BMXV Highest task virtual address. When the task does not 
have memory-resident overlays, the value is set to 
L$BHGV. 

L$BLDZ Task load size in units of 64-byte blocks. This value 
represents the size of the root segment. 

L$BMXZ Task maximum, size in units of 64-byte blocks. This 
value represents the size of the root segment plus any 
additional physical memory needed to contain task 
overlays. 

L$BOFF Task offset into partition in units of 64-byte blocks. 
This value represents the size of the mapped array area, 
which precedes the task's code and data in the 
partition. 

L$BWND Number of task window blocks less library window blocks 
— Low byte 

L$BSYS System ID ~ High byte 

L$BWND Number of task windows (excluding resident libraries) . 

L$BSEG Size of overlay segment descriptors (in bytes) . 

L$BFLG Task flags word. The following flags are defined: 

Meaning When Bit = 1 

Task contains position-independent code 
(PIC) . 

Task has no header . 

Task is ancillary control processor. 

Task generates Postmortem Dump. 

Task can be slaved. 

No SEND can be directed to task. 

(Not used) 

Task is privileged. 

Task is built in compatibility mode. 

Task is not checkpointable. 

Task has memory-resident overlays. 

(continued on next page) 



Bit 


Flag 


15 


TS$PIC 


14 


TS$NHD 


13 


TS$ACP 


12 


TS$PMD 


11 


TS$SLV 


10 


TS$NSD 


9 




8 


TS$PRV 


7 


TS$CMP 


6 


TS$CHK 


5 


TS$RES 
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Table B-1 (Cont.) 
Task and Resident Library Data 



Parameter 



Definition 



L$BFLG 
(Cont.) 



Bit Flag 

4 TS$IOP 

3 TS$SUP 

2 TS$XHR 

1 TS$NXH 



Meaning When Bit = 1 

Privileged task does not map I/O page 

Image linked as supervisor-mode library 
(RSK-llM-PLUS systems only) . 

Task was built with external header 

Task was built with pool resident 
header (non external) 



L$BDAT 



L$BLIB 
L$BPRI 
L$BXFR 

L$BEXT 

L$BSGL 

L$BHRB 
L$BBLK 
L$BLUN 
L$BROB 
L$BROL 
L$BRDL 
L$BHDB 
L$BDHV 
L$BDMV 
L$BDLZ 
L$BDMZ 



Three words containing the task creation date as 2-digit 
integer values as follows: 

• Year since 1900 

• Month of year 

• Day of month 
Resident library entries. 

Task priority set by the PRI keyword. 

Task transfer address. Used to initiate a bootable core 
image, for example, the resident executive. 

Task extension size in units of 32-word blocks. This 
parameter is set by the EXTTSK keyword. 



Relative block number of segment load list, 
no list is allocated. 

Relative block number of header. 

Number of blocks in label block group. 

Number of logical units. 

Relative block number of R/0 image. 

R/0 load size in 32-word blocks. 

Size of R/0 data in 32-word blocks. 

Relative block number of data header. 

High vitrual address of data window 1. 

High virtual address of data. 

Load size of data 

Maximum size of data 



Set to if 
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Offset 



LSBTSK 







2 


L$BPAR 


4 




6 


L$BSA 


10 


L$BHGV 


12 


L$BMXV 


14 


L$BLDZ 


16 


L$BMXZ 


20 


L$BOFF 


22 


L$BWND/L$BSYS 


24 


L$BSEG 


26 


L$BFLG 


30 


L$BDAT 


32 




34 




36 


LSBLIB 


40 




42 




44 




46 




50 




52 




54 




56 




60 




62 




64 




66 




70 




72 




: 




344 


LSBPRI 


346 


LSBXFR 


350 


LSBEXT 


352 


LSBSGL 


354 


L$BHRB 


356 


L$BBLK 


360 


L$BLUN 


362 


LSBROB 


364 


LSBROL 


366 


LSBRDL 


370 


LSBHDB 


372 


LSBDHV 


374 


LSBDMV 


376 


LSBDLZ 


400 


LSBDMZ 


402 



Task 



Name 



Task 



Partition 



Base address of task 



Highest window virtual address 



Highest virtual address in task 



Load size in 64-byte blocks 



Maximum size in 64-byte blocks 



Task offset into partition 



System KD, I Number of window blocks* 



Size of overlay segment descriptors 



Task flag word 



Task creation date — Year 



— Month 



-Day 



Library/common 



Name 



Base address of library 



Highest address in first library window 



Highest address in library 



Library load size |64-byte blocks) 



Library maximum size {64-byte blocks) 



Library offset into region 



Number of library window blocks 



Size of library segment descriptors 



Library flag word 



Library creation date — Year 



- Month 



- Day 



R$LNAM 

R$LSA 

RSLHGV 

R$LMXV 

RSLLDZ 

RSLMXZ 

RSLOFF 

R$LWND 

RSLSEG 

R$LFLG 

RSLDAT 



Library 
Request 
'{maximum 
of 7 

14-«rord 
entries irv 
RSX-IlM systems 
and 
maximum' 

14-w6rd:' 
entries m ' 

Rsx-tm+Msi^h', 



Task priority 



Task transfer address 



Task extension (64-byte blocks) 



Block number of segment load list 



Block number of header 



Number of blocks in label 



Number of logical units 



Relative block of R-0 image 



R/0 load size 



R/0 data size in 32-word blocks 



Relative block number of data header 



High virtual address of data window 1 



High virtual address of data 



Load size of data 



Maximum size of data 



] • 



Less library window blocks. 

ZK-475-81 



Figure B-5 Label Block — Task and Resident Library Data 

Table B-2 describes the contents of the resident shared region name 
block. TKB constructs this block by referring to the disk image of 
the resident shared region. The format is identical to words 3 
through 16 of the label group block. 
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Table B-2 
Resident Library/Common Name Block Data 



Parameter 



Definition 



R$LNAM Shared region name consisting of 2 words in Radix-50 
format. 

R$LSA Base virtual address of library or common. 

R$LHGV Highest address mapped by first library window. 

R$LMXV Highest virtual address in library or common. 

R$LLDZ Shared region load size in 64-byte blocks. 

R$LMXZ Library maximum size in 64-byte blocks. This value 
represents the size of the root segment plus the sum of 
all memory-resident overlays. 

R$LOFF Size of mapped array space allocated by resident 
library. This value is added to the mapped array area 
of the task. 

R$LWND Number of window blocks required by library. 

R$LSEG Size of library overlay segment descriptors in bytes. 

R$LFLG Library flags word. The following flags are defined: 

Bit Meaning 

15 LD$ACC — Access intent (l = read/write , 
O=read-only) 

14 LD$RSV — APR was reserved 

13 LD$CLS — Library is part of a cluster 

3 ; lJa$sav — 'Super visjqr-fflode library (l=yesjt 

2 LD$REL — Position-independent code (PIC) flag 
(1=PIC) 

1 LD$TYP — Shared region type (1 = common, 
= library) 

R$LDAT Three words containing the shared region creation date 
in 2-digit integer values as follows: 

• Year since 1900 

• Month of year 

• Day of month 



The table of LUN assignments, illustrated in Figure B-6, contains the 
name and logical unit number of each device assigned. Label block 2 
(the second block of LUN assignments) is allocated only if the number 
of LUNs exceeds 128. 
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TKB creates the segment load list if the image contains only 
memory-resident overlays. The segment load list is used only in 
RSX-llS systems for loading tasks that have resident overlays. Figure 
B-7 illustrates the segment load list. Each entry in the list gives 
the length, in bytes, of a memory-resident overlay segment. 







Device name 


LUN 1 


Label 
Block 
1 




Unit number 




• 
• 
• 






Device name 






LUN 128 




Unit number 












Device name 


LUN 129 


Label 
Block 
2 




Unit number 




• 
• 
• 






Device name 


LUN 255 






Unit number 



Figure B-6 Label Blocks 1 and 2 — Table of LUN Assignments 



Length of root segment 


Length of first overlay segment 


Length of second overlay segment 


• 
• 
• 






ZK-477-81 

Figure B-7 Label Block 3 — Segment Load List 



B.2 CHECKPOINT AREA 

The checkpoint area is created by the /AL switch (refer to Chapter 
10) . The checkpoint area is as large as the task image plus any areas 
created by the EXTTSK, PAR, or VSECT options. The checkpoint area 
does not include space for the external header if the /XH switch was 
specified . 
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B.3 HEADER 



As shown in Figures B-1 through B-4 , the task header starts on a block 
boundary and is immediately followed by the task image. The header is 
read into memory with the task image. 

The header is divided into two parts: a fixed part as shown in Figure 
B-8; and a variable part as shown in Figure B-9. The offsets for the 
fixed part are defined by macro HDRDFS residing in LB: [1,1] EXEMC.MLB. 

The variable part of the header contains window blocks that describe 
the following: 

• The task's virtual-to-physical mapping 

• Logical unit data 

• Task context 

Although the header is fully accessible to the task, you should 
consider only the information in the low-memory context (H.DSW through 
H.VEXT) in the fixed part of the header to be accurate. In a mapped 
system, the Executive copies the header of an active task to protected 
memory. Subsequent Executive updates to the header are made to this 
copy, not to the header copy within the running task. 

The following sections provide more detail on the low-memory context 
and on Logical Unit Table entries (the Logical Unit Table is part of 
the variable part of the header; see Figure B-9). 

NOTE 

To save the identification, you should 
move the initial value set by the Task 
Builder to local storage. When the 
program is fixed in memory and being 
restarted without being reloaded, you 
must test the reserved program words for 
their initial values to determine 
whether the contents of R3 and R4 should 
be saved. 

The contents of RO , Rl, and R2 are only 
set when a debugging aid is included in 
the task image. 



B.3,1 Low-Memory Context 

The low-memory context for a task consists of the Directive Status 
Word and the impure area vectors. TKB recognizes the following global 
names : 

Name Meaning 

.FSRPT File Control Services work area and buffer pool vector 

$OTSV FORTRAN OTS work area vector 

N.OVPT Overlay run-time system work area vector 

$VEXT Vector extension area pointer 
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Label ( 


3ffset 


H.CSP 





H.HDLN 


2 


H.EFLM 


4 




6 


H.CUIC 


10 


H.DUIC 


12 


H.IPS 


14 


H.IPC 


16 


H.ISP 


20 


H.ODVA 


22 


H.ODVL 


24 


H.TKVA 


26 


H.TKVL 


30 


H.PFVA 


32 


H.FPVA 


34 


H.RCVA 


36 


H.EFSV 


40 


H.FPSA 


42 


H.WND 


44 


H.DSW 


46 


H.FCS 


50 


H.FORT 


52 


H.OVLY 


54 


H.VEXT 


56 


H.SPRI/H.NML 


60 


H.RRVA 


62 




64 




66 




70 


H.GARD 


72 


H.NLUN 


74 



Current Stack Pointer (R6) 



Header length 



Event flag mask 



Event flag address 



Current UIC 



Default UIC 



Initial PS 



Initial PC (R7) 



Initial Stack Pointer (R6) 



ODT SST vector address 



ODT SST vector length 



Task SST vector address 



Task SST vector length 



Power fail AST control block 



Floating-point AST control block 



Receive AST control block 



Address of event flag context 



Address of floating-point context 



flb*S?e==t;|fM«4Ei:as,>-' 



m:sm4p-' 



7«,pMAe*' 






-^ 



Pointer to number of window blocks 



Directive Status Word 



Address of FCS impure storage 



Address of FORTRAN impure storage 



Address of overlay impure storage 



Address of impure vectors 



Mailbox LUN 



Swapping priority 



Receive by reference AST control block 



Reserved 



H.X25 



Reserved 



Reserved 



Header guard word pointer 



Number of LUNs 



Low-Core 
Context 



Figure B-8 Task Header, Fixed Part 



The only proper reference to these pointers is by symbolic name. The 
pointers are read-only. If you write into them, the result will be 
lost on the next context switch. 

The impure area pointers contain the addresses of the storage used by 
the reentrant library routines listed above. 
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The address contained in the vector extension pointer locates an area 
of memory that can contain additional impure area pointers. 



H.LUN LUN Table (2 words per LUN) 



Number of window blocks 



Partition control block address 



Low virtual address limit 



High virtual address limit 



Address of attachment dexriptor 



Window size (in 32-word blocks) 



Offset into partition (in 32-word blocks) 



Number of PDRs to Map 



First PDR Address 



Contents of last PDR 



Offsets 

W.BPCB 

W.BLVR 

W.BHVR 

W.BATT 

W.BSIZ 

W.BOFF 

W.BNPD/W.BFPD 

W.BLPD 



Current PS 




Current PC 


Initial Values 


Current R5 


Relative block number of header 


Current R4 


Ident. word #2 


Current R3 


Idem, word #1 


Current R2 


Task name word #2 


Current R 1 


Task name word #1 


Current RO 


Program transfer address 


Header guard word 





Figure B-9 Task Header, Variable Part 



Figure B-10 illustrates the format of th 
location within this area contains th 
area that can be referred to by subrouti 
these subroutines must be reentrant, 
(location $VEXTA) is contained at absolu 
header. Addresses below $VEXTA, refer r 
reserved for DIGITAL applications. Addr 
to by positive offsets, are allocated fo 



e vector extension area, 
e address of an impure sto 
nes within a resident libr 

The address of this 
te address $VEXT in the 
ed to by negative offsets, 
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r user applications. 
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area 
task 
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B-12 



DETAILED TASK IMAGE FILE STRUCTURE 



$VEXT 



$VEXTA 



.PSECT $$VEXO 



.PSECT $$VEX1 



Reserved for 
DIGITAL use 



Reserved for 
user applications 



Figure B-10 Vector Extension Area Format 



The program sections $$VEXO and $$VEX1 have the attributes D, GBL, RW, 
REL, and OVR. 

The program section attribute OVR facilitates defining the offset to 
the vector and initializing the vector location at link time. For 
example : 

.GLOBL $VEXTA ; MAKE SURE VECTOR AREA IS LINKED 

.PSECT $$VEX1,D,GBL,REL,0VR 

; POINT TO BASE OF POINTER TABLE 



$$$=■ 



.BLKW N 



LABEL: 
OFFSET==LABEL-BEG 

.PSECT 

IMPURE: 



; OFFSET TO CORRECT LOCATION 
; IN VECTOR AREA 



.WORD IMPURE ; SET IMPURE AREA ADDRESS 



; DEFINE OFFSET 



You should centralize all offset definitions within a single module 
from which the actual vector space allocation is made. Also, you 
should write the source code with conditional statements to create two 
object modules: one that reserves the vector storage; and one that 
defines the global offsets that will be referred to by your resident 
library's subroutines. 

Note that the sequence of instructions above intentionally redefines 
the global symbol. The Task Builder reports an error if this value 
differs from the centralized definition. 
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You can locate your vector through a sequence of instructions similar 
to the following: 

MOV @#VEXT,RO ; GET ADDRESS OF VECTOR EXTENSIONS 

MOV OFFSET(RO) ,R0 ; POINT TO IMPURE AREA 

.END 



B.3.2 Logical Unit Table Entry 

Figure B-11 illustrates the format of each entry in the Logical Unit 
Table. 



UCB address 



Window block pointer 
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Figure B-11 Logical Unit Table Entry 

The first word contains the address of the device unit control block 
in the Executive system tables. That block contains device-dependent 
information. 

The second word is a pointer to the window block if the device is file 
structured. 

The UCB address is set during task installation if a corresponding ASG 
parameter is specified at task-build time. You can also set this word 
at run time with the Assign LUN Directive to the Executive. 

The window block pointer is set when a file is opened on the device 
whose UCB address is specified by word 1. The window block pointer is 
cleared when the file is closed. 



B.4 TASK IMAGE 

The system reads the task image into memory beginning with the task 
header (see Figures B-1 through B-4) . The root segment of a 
conventional task image is a set of contiguous disk blocks; it is 
therefore loaded with a single disk access. However, an I- and 
D-space task root contains 2 sets of contiguous blocks. Therefore, an 
I- and D-space task requires two disk accesses, one for the D-space 

Par-f- jan^ orvci ^t^-v +-K^ T^cr\^/-ie r^ -n »■ 4- rnV»« r» nv^^^^ «^^«a. 4— l^.jr_j ^_*„_±_ 

'-- * <=*i^-. K^t*^ ^wa_ i^fcjv- A^&^^^fc pcij.u. j.iJf:z u— oj^a*^c ^di. u xB xOoCieu XJ.LSC. 

Additionally, each segment of an overlaid I- and D-space task requires 
two disk accesses if it contains both I- and D-space. 

Each overlay segment of the task image begins on a block boundary (see 
Figure B-3) . Note that a given overlay segment occupies as many 
contiguous disk blocks as it needs to supply its space request. The 
maximum size for any segment, including the root, is 32K minus 32 
words. 
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NOTE 

One exception to the block boundary 
alignment of segments occurs when shared 
regions contain resident overlays. When 
this occurs, the image is compressed 
and, instead of being aligned on block 
boundaries, segments are aligned on 
32-word boundaries. This facilitates 
the loading of regions. 



Figures B-12 and B-13 illustrate the structure 
components of the task-resident overlay data base. 
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Window descriptors are necessary for the 
windows that the Overlay Run-Time 
System uses to map memory resident 
overlays. The Overlay Run-Time System 
also needs window descriptors to map 
disk-resident overlays that are up-tree 
from memory-resident overlay segments. 

The Overlay Run-Time System uses 
region descriptors to map overlaid 
libraries. 



Figure B-12 Task-Resident Overlay Data Base 
for a Conventional Overlaid Task 
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Window descriptors are necessary for the 
windows that the Overlay Run-Time 
System uses to map memory resident 
overlays. The Overlay Run-Time System 
also needs window descriptors to map 
disk-resident overlays that are up-tree 
from memory-resident overlay segments. 

The Overlay Run-Time System uses 
region descriptors to map overlaid 
libraries. 



Figure B-13 Task-Resident Overlay Data Base 
for an 1- and D-Space Overlaid Task 



Autoload vectors are generated whenever a reference is made to an 
autoloadable entry point in a segment located farther away from the 
root than the segment making the reference. 

One segment descriptor is generated for each overlay segment in the 
task or shared region. The segment descriptor contains information on 
the size, virtual address, and location of the segment within the task 
image file. In addition, it contains a set of link words that point 
to other segments. The overlay structure determines the link word 
contents . 
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Segment .descriptors .for i- arid D-space tasks .halve art extension for ;the; 
'D-Spaice, patt^ 'thkt^:\<ioHtains' vthei,-' disk block' address,- vixtiiaiApad 
;^addre'ss',; segment leTjgth in bytes,; and- window pointer,'; ^ '-;;/ 

The window descriptor contains information required to issue the 
mapping directives. TKB allocates one window descriptor for each 
memory-resident overlay in the structure. 

The region descriptor contains information required to attach a 
resident library or common block. There is one region descriptor for 
each shared region containing memory-resident overlays. 

The following sections describe each data base component in greater 
detail = 



B.4.1 Autoload Vectors for Conventional Tasks 

The autoload vector table consists of one entry (put into the task 
image for each autoload entry point) in the form shown in Figure B-14. 



JSR PC,@.NAUTO 



PC RELATIVE OFFSET TO .NAUTO 



SEGMENT DESCRIPTOR ADDRESS 



ENTRY POINT ADDRESS 



ZK-1070-82 

Figure B-14 Autoload Vector Entry for Conventional Tasks 

The autoload vector executes an indirect JSR instruction to $AUTO 
through .NAUTO. Following the JSR instruction is a pointer to the 
descriptor for the segment to be loaded. Following the descriptor is 
the real address of the required entry point. 



B.4.2 Autoload Vectors for I- and D-Space Tasks 

The autoload vector table consists of two entries (put into the task 
image for each autoload entry point) in the form shown in Figure B-15. 

The I-spacc part of the autoload vector' .contains a MQV ins:tructipn 
that places the address ,of the D-space part of the ;yeptor on the 
stack. The vector -then executes an indirect JMP to $AUTO through/ 
.NAUTO. The D-space part of the vector contains the segment 
descriptor address and the entry point address of the required 
routine. 
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MOV (PC) + , -(SP) 


ADDRESS OF PACKET (D-SPACE) 


JMP @.NAUTO 


PC RELATIVE OFFSET TO .NAUTO 



l-SPACE PORTION 



ADDRESS OF SEGMENT DESCRIPTOR 



ENTRY POINT ADDRESS 



D-SPACE PORTION 



ZK-1071-82 



Figure B-15 Autoload Vector Entry for I- and D-Space Tasks 



B.4.3 Segment Descriptor 

The segment descriptor for a conventional task consists of a fixed 
part and two optional parts. The fixed part is six words long. If 
the manual-load feature is used ($LOAD) , two words are added 
containing the segment name. When a memory-resident overlay structure 
is included, a ninth word is appended that points to the window 
descriptor . 

The segment descriptor for an I- and D-space task consists of a fixed 
part that is 9 words long and an optional part that is 4 words long. 
This optional part is always present for task segments and not present 
for library segments. 

Figure B-16 illustrates the contents of the segment descriptor. 
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TASK-RESIDENT SEGMENT DESCRIPTOR OFFSETS 
15 12 11 



FLAGS 



RELATIVE DISK BLOCK ADDRESS 



VIRTUAL LOAD ADDRESS OF SEGMENT 



LENGTH OF SEGMENT IN BYTES 



LINK UP 



LINK DOWN 



LINK NEXT 



SEGMENT NAME (2-WORD RADIX 50) 



WINDOW DESCRIPTOR ADDRESS 



BYTE 

2 
4 

6 

10 
12 

14 

20 



FLAGS: 15-TASK RESIDENT FLAG (ALWAYS 1) 

14-SEGMENT HAS DISK ALLOCATION (1=N0) 
13-SEGMENT IS LOADED FROM DISK (1=YES) 
12-SEGMENT IS LOADED AND MAPPED (0=YES) 






•15,::' 



'^iW::n.Cy" 



:.,or; 



...tl^SEiS;-, 



2rD7;g;pAc6::pisCBfcO.(;«'A 



sjjgi'i^A|p:'«i|Ty^l::;;£<jA:i5;* 



:f:;;-;^"!jg|5|fe^ 



?'C5)=^iezte!£jtitp 






.H,!^ ;,■ p iiftjj,, J. ^"s> " E- ":^i- "' ■ ■'"■ " i. ' "5;i.a).. ■ 'l ■■ ■■ "!!■■!«„ ■ M!!«', ■"■"■■■111.!..: '"■"••• ■'Z.*\-i-IU/ t-at 

Figure B-16 Segment Descriptor 

Word contains the relative disk address in bits through 11 and the 
segment status in bits 12 through 15. Each segment in the task image 
file begins on a disk block boundary. The relative disk address is 
the block number of the segment relative to the start of the root 
segment. The segment status flags are defined as follows: 



Bit 

15 
14 

13 

12 



Setting 



Always set to 1 



= Segment has disk allocation. 

1 = Segment does not have disk allocation. 

= Segment is not loaded from disk. 

1 = Segment is loaded from disk. 

= Segment is loaded and mapped. 

1 = Segment is either not loaded or not mapped, 
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Word 1 contains the load address of the segment. This address is the 
first virtual address of the area where the segment will be loaded. 

Word 2 specifies the length of the segment in bytes. 

Words 3, 4, and 5 point to the following segment descriptors: 

• Link up — The next segment away from the root {O = none) . 

• Link down — The next segment toward the root (O=none) . 

• Link next — The adjoining segment; the link-next pointers 
are linked in circular fashion. 

When the system loads a segment, the overlay run-time system follows 
the links to determine which segments are being overlaid and should 
therefore be marked out of memory. For example: 

A21 A22 



Al 



A2 



AO 
The segment descriptors are linked as follows; 



Al 
L 



A21 



A22 



A2 



A21 

Sr 


A22 


A21 - , 


Al A2 
1 1 


Al - ^ R9 


AO 




Q 


link down 




link next 



AO 

link up 

If there is a co-tree, the link next for the root segment descriptor 
points to the co-tree root segment descriptor. 

Words 6 and 7 contain the segment name in Radix-50 format. 

Word 8 points to the window descriptor used to map the segment 
(O = none) . 



B.4.4 Window Descriptor 

TKB allocates window descriptors only if you define a structure 
containing memory-resident overlays. Figure B-17 illustrates the 
format of a window descriptor. 

Words through 7 constitute a window descriptor in the format 
required by the mapping directives. If the memory-resident overlay is 
part of the task, the region ID is 0. If the memory-resident overlay 
is part of a shared region, the overlay loading routine fills in the 
ID at run time. 

Words 8 and 9 contain additional data that is referred to by the 
overlay routines. Bit 15 of the flags word, if set, indicates that 
the window is currently mapped into the task's address space. 
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Word 9 contains the address of the associated region descriptor. If 
the memory-resident overlay is part of the task, and no region 
descriptor is allocated, this value is 0. 



Word 

1 
2 
3 
4 
5 
6 
7 
8 
9 



15 



8 7 



Base Active Page Register 



Window ID 



Virtual base address 



Window size in 64-byte blocks 



Region ID 



Offset in partition 



Length to map 



Status word 



Send/receive buffer address (always 0) 



Flags word 



Address of region descriptor 



Figure B-17 Window Descriptor 



B.4.5 Region Descriptor 

The region descriptor is allocated only when the memory-resident 
overlay structure is part of a shared region. Figure B-18 illustrates 
the format of a region descriptor. 

Word 




1 
2 
3 
4 
5 
6 
7 
8 



Region ID 



Size of region 



Region 
name 



Region 
partition 



Region status 



Protection codes (always 0) 



Flags 



Figure B-18 Region Descriptor 
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Words through 7 constitute a region descriptor in the format 
required by the mapping directives. The flags word is referred to by 
the overlay load routine. Bit 15 of the flags word, if set, indicates 
that a valid region identification is in word 0. If this bit is 
clear, the overlay load routine issues an Attach Region directive 
(with protection code set to 0) to obtain the identification. 
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C.l INTRODUCTION 

You can build a task on one system (the host) , and run it on another 
(the target) . For example, your installation might consist of one 
large computer system with mapping hardware, and several smaller 
unmapped systems. On the large system you could create and debug 
tasks, and then transfer them to the smaller systems to run. 

For example, if you are developing a task named TK3, using the default 
partition of your host system, the TKB command could be: 

>TKB TK3,TK3=SQ1,SQ2 

Vlhen you are ready to move TK3 to a target system, you build it again, 
indicating the mapping status of the target system and naming the 
partition in which the task is to reside: 

>TKB 

TKB>TK3/-MM,TK3=SQ1 , SQ2 

TKB>/ 

Enter Options: 

TKB>PAR=PART1: 100000: 40000 

TKB>// 

The resulting task image is ready to run on the unmapped target 
system. 

You can transfer a task from the host system to the target system by 
following these steps: 

1. Build the task image specifying the partition in which the 
task will run. If the target system is an unmapped system, 
specify the partition's base address and size. 

2. Ensure that any shared regions accessed by the task are 
present in both systems. 

3. If the target system and the host system do not have the same 
mapping status, set the Memory Management switch (/MM or 
/-MM) to reflect the mapping status of the target system. 

The task code must not use any hardware options (FPP, EIS, EAE, and so 
forth) that are not present on the target system. This is 
particularly important if you are a FORTRAN user because FORTRAN tasks 
often use mathematics routines that are hardware dependent. (Refer to 
the IAS/RSX-11 FORTRAN IV Installation Guide and the IAS/RSX-11 
FORTRAN IV User's Guide for more information on FORTRAN requirements) . 
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C.2 EXAMPLE C-1: TRANSFERRING A TASK FROM A HOST TO A TARGET SYSTEM 

In this section, the resident library LIB and the task that refers to 
it, MAIN (from Example 4, Chapter 5), are rebuilt to run on an 
unmapped system. To save space, only the Task Builder command 
sequences are shown. 

Assuming that the target system has a partition within it named LIB, 
you need to make only two changes to the original command sequence 
that builds the library: 

1. You must attach the negated memory management switch (/-MM) 
to the image file specification. 

2. You must specify the partition base and length. 

The modified command sequence is as follows: 

TKB>LIB/-HD/PI/-MM,LIB/-WI,LIB=LIB 

TKB>/ 

Enter Options: 

TKB>STACK=0 

TKB>PAR=LIB: 136000: 20000 

TKB>// 

If the target system does not contain a partition of the same name as 
that of the shared region, you must change the name of the shared 
region to match the name of an existing partition in the target 
system. This is a requirement of RSX-llM; on RSX-llM-PLUS systems it 
is not. 

Assuming that the target system has a partition named GEN and that the 
task MAIN is to run in that partition in the target system, you must 
make three changes to the command sequence that builds the task MAIN: 

1. You must attach the negated memory management switch (/-MM) 
to the task image file specification. 

2. You must eliminate the APR parameter of the RESLIB keyword. 

3. You must explicitly specify the base address and length of 
the partition in which the task is to reside. 

The modified command sequence is as follows: 

TKB>MAIN/-MM,MAIN/MA/-WI=MAIN 

TKB>/ 

Enter Options: 

TKB>RESLIB=LIB/RO 

TKB>PAR=GEN: 30 100: 40000 

TKB>// 

Example C-1, Part 1 shows the map file of the resident library LIB for 
an unmapped system. LIB is bound to the partition base specified by 
the PAR keyword in the task-build command sequence. Note that the 
shared region is declared position independent even though it is bound 
to the partition base 136000. The position-independent declaration is 
not necessary in this example because the referencing task MAIN does 
not require the program section names within the library in order to 
refer to it. However, in applications involving tasks that require 
the program section names from the library, you must declare the 
library position independent so that TKB will place the program 
section names in the library's symbol definition file. 
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Example C-1, Part 1 Task Builder Map for LIB.TSK 



LIB.TSK;! Memory allocation map TKB M40.10 Page 1 

lO-DEC-82 11:50 



Partition name : LIB 

Identification : 01 

Task UIC : [303,3] 

Task attributes: -HD,PI 

Total address windows: 1. 

Task image size : 64. words 

Task address limits: 000000 000163 

R-W disk blk limits: 000002 000002 000001 00001. 

*** Root segment: LIB 



R/W mem limits: 000000 000163 000164 00116. 
Disk blk limits: 000002 000002 000001 00001, 



Memory allocation synopsis: 

Section Title Ident File 



. BLK. : (RW,I,LCL,REL,CON) 
AADD : (RO,I,GBL,REL,CON) 

DIVV : (RO,I,GBL,REL,CON) 

MULL : (RO,I,GBL,REL,CON) 

SAVAL : (RO,I,GBL,REL,CON) 

SUBB : {RO,I,GBL,REL,CON) 



000000 


000000 


00000 


000000 


000024 


00020 


000000 


000024 


00020 


000024 


000026 


00022 


000024 


000026 


00022 


000052 


000024 


00020 


000052 


000024 


00020 


000076 


000042 


00034 


000076 


000042 


00034 


000140 


000024 


00020 


000140 


000024 


00020 



LIB 01 LIB.0BJ;1 

LIB 01 LIB.0BJ;1 

LIB 01 LIB.OBJjl 

LIB 01 LIB.0BJ;1 

LIB 01 LIB.OBJ;! 



Global symbols: 

AADD 000000-R MULL 000052-R SUBB 000140-R 
DIW 000024-R SAVAL 000076-R 



*** Task builder statistics: 

Total work file references: 368. 

Work file reads: 0. 

Work file writes: 0. 

Size of core pool: 7086. words (27. PAGES) 

SIZE OF WORD FILE: 768. words (3. PAGES) 

Elapsed time:00:00:03 
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Example C-1, Part 2 shows the map file of the task MAIN for an 
unmapped system. The task is bound to the partition base 30100 and 
linked to the shared region LIB, which begins at 136000. 



Example C-1, Part 2 Task Builder Map for MAIN.TSK 



MAIN.TSK;1 Memory allocation map TKB M40.10 Page 1 

ll-DEC-82 13:41 



Partition name : GEN 

Identification : 01 

Task UIC : [303,3] 

Stack limits: 000274 001273 001000 00512. 

PRG xfr address: 001634 

Total address windows: 2. 

Task image size : 1152. WORDS 

Task address limits: 00000 004327 

R-W disk blk limits: 000002 000006 000005 00005. 

*** Root segment: MAIN 



R/W mem limits: 000000 004327 004330 02264 
Disk blk limits: 000002 000006 000005 00005. 



Memory allocation synopsis; 



Section 



Title Ident File 



BLK.: (RW,I,LCL,REL,CON) 001274 002620 01424. 

001274 000530 00344, 



MAIN 



01 



MAIN.OBJ;! 



Global symbols; 



AADD 160000-R 
DIVV 160000-R 
lO.WVB 011000 
MULL 060000-R 



SAVAL 060000-R 
SUBB 060000-R 
$CBDAT 003074-R 
$CBDMG 003102-R 



$CBDSG 003110-R 
$CBOMG 003116-R 
$CBOSG 003124-R 
$CBTA 003154-R 



$CBTMG 003132-R 
$CBVER 003116-R 
$CDDMG 003656-R 
$CDTB 003312-R 



*** Task builder statistics: 

Total work file references: 1889. 

Work file reads: 0. 

Work file writes; 0. 

Size of core pool: 7086. WORDS (27. 

Size of work file: 1024, WORDS (4. 



PAGES ) 
PAGES) 



Elapsed time:00:00:07 
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The RSX-llM/M-PLUS Postmortem Dump task (PMD) generates postmortem 
memory dumps of tasks that are abnormally terminated. In addition, 
PMD can produce edited dumps, called snapshot dumps, for tasks that 
are running. Section D.l describes Postmortem Dumps in general; 
Section D.2 discusses the specific case of snapshot dumps. Both types 
of dumps are very useful debugging aids. 



D.l POSTMORTEM DUMPS 

You can make a task eligible for a Postmortem Dump in any of three 
ways: 

• At task-build time, by specifying the /PM switch for the task 
file. /-PM disables dumps; it is the default condition. 

• When you install a task by using the /PMD switch to override 
the taskbuild option. /PMD=YES enables dumping; /PMD=NO 
disables dumping. 

• When you use the MCR command ABORT (described in the 
RSX-llM/M-PLUS MCR Operations Manual ) , by including the PMD 
switch in the command line to specify a dump. 

You should install PMD in a 4K partition in which all other tasks are 
checkpointable. This allows the dump to be generated in a timely 
manner, and prevents the system from being locked up while the dump is 
being generated. PMD can dump either from memory or from the 
checkpoint image of your task. The PMD is sensitive to the location 
of the aborted task; therefore, if the aborted task is checkpointed 
during the dump, PMD switches to reading the checkpoint image. Once 
the task is checkpointed, PMD locks it out of memory until it has 
completed formatting the dump. 

Dumps are always generated on the system disk under UFD [1,4]; 
therefore, to avoid errors from PMD, you must create a UFD for [1,4] 
before installing the task. When PMD finishes generating the dump, it 
attempts to queue the dump to the print spooler for subsequent 
printing. If no spooler is installed, the dump file is left on the 
disk and can be printed at a later time using the Peripheral 
Interchange Program (PIP, described in the RSX-11 Utilities Manual ) . 

NOTE 

Dump files tend to be somewhat large. 

The dump of an 8K partition averages 

about 340 blocks. Therefore, if there 

is little space on the disk, it is 

important to print and delete the dump 
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file without delay. The print spooler 
automatically deletes all files with the 
type .PMD after printing them. 



Example D-1 shows the contents of a Postmortem Dump and snapshot dump; 
the notes that follow the figure are keyed to the figure and provide a 
description of the dumps contents. Snapshot Dumps are explained more 
fully in Section D.2. 



TIME: 5-OCT-76 15:06 



Example D-1 Sample Postmortem Dump (Truncated) 

POST-MORTEM DUMP 
TASK: TT6 Q 

PC: 000720 Q lOT EXECUTION Q 

REGS: RO - 000345 Rl - 074400 R2 - 000120 R3 - 140130 
R4 - 000000 k5 - 000000 SP - 000304 PS - 170000 
TASK STATUS: MSG AST DST -CHK HLT STP REM MCR 
EVENT FLAG MASK FOR <1-16> 000001 Q 
CURRENT UIC: [007,001] DSW: l.O 

PRIORITY: DEFAULT - 50. RUNNING - 50. I/O COUNT: 0. TI DEVICE - TT6:® 
LOAD DEVICE - DBO : LBN: 1,160034© 



INC 


I POINT UNIT 


STATUS - 000000 


RO 


- 000000 


000000 


Rl 


- 000000 


000000 


R2 


- 000000 


000000 


R3 


- 000000 


000000 


R4 


- 000000 


000000 


R5 


- 000000 


000000 



^ 



000000 000000 V /rv 

000000 000000 ' ^ 

000000 000000 

000000 000000 

000000 000000 



LOGICAL UNITS 



UNIT DEVICE 

1 DBO: 

2 DBO: 

3 DBO: 

4 DBO: 



000000 000000 



-\ 



y 



FILE STATUS 



® 



y 



OVERLAY SEGMENTS LOADED AND RESIDENT LIBRARIES MAPPED 



STARTING RELATIVE BLOCK: 000002 BASE: 000000 
STARTING RELATIVE BLOCK: 000004 BASE: 001454 



LENGTH: 001454 
LENGTH: 000264 



® 



TASK STACK 

ADDRESS CONTENTS ASCII RAD50 
000304 000045 % 7 



® 



TASK IMAGE 



(continued on next page) 
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Example D-1 (Cont.) Sample Postmortem Dump (Truncated) 



PARTITION 


: GEN 


VIRTUAL LIMITS: 000000 - 


0017 


77 










000000 


000304 


000162 


000001 


067426 ! 


D6 


B4 


A 


Q08! 












304 000 


162 000 


001 000 


026 157 








!D 


r 




o ! 




000010 


003401 
001 007 


003401 
001 007 


170017 
017 360 


000352 1 
352 000 


ADS 


AD 3 


8PQ 


E4! 
I 




P 


J i 




000020 


000304 
304 000 


000000 
000 000 


000000 
000 000 


000000 ! 
000 000 


D6 






! 
!D 










000030 


000000 
000 000 


000000 
000 000 


000000 
000 000 


000000 ! 
000 000 








• 










000040 


000000 
OQO 000 


140162 
162 300 


074106 
106 170 


000001 ! 
001 000 




OIZ 


SIO 


A! 

! 


r§ 


Fx 






000050 


000000 
000 000 


000000 
000 000 


001104 
104 002 


000000 • 
000 000 






NT 


1 
! 




D 






000060 


000373 
373 000 


000000 
000 000 


000000 
000 000 


000000 . 
000 000 


Fk 






1 

! 










000070 


000000 
000 000 


074150 
150 170 


000004 
004 000 


051646 . 
246 123 




SJX 


D 


MONj 

! 


hx 




&S! 




000100 


000000 
000 000 


051646 
246 123 


000000 
000 000 


051646 . 
246 123 




MON 




MON! 
1 


&S 




&S! 




000110 


000000 
000 000 


051646 
246 123 


000000 
000 000 


000001 
001 000 




MON 




A! 
1 


&S 








000120 


067020 
020 156 


000000 
000 000 


001777 
377 003 


061404 
004 143 


QXP 




YW 


03.! 
! n 






c! 




000130 


000020 
020 000 


000000 
000 000 


000600 
200 001 


007406 
006 017 


P 




IX 


BPF! 
1 










000140 


170000 
000 360 


000720 
320 001 


000000 
000 000 


000000 
000 000 


8P 


KX 




1 

i p 


P 








000150 


140130 


000120 


074400 


000345 


01 


B 


SNP 


E/! 








y (^ 




130 300 


120 000 


000 171 


345 000 








!x@ 


P 


y 


e ! 




000160 


000000 
000 000 


000000 
000 000 


000000 
000 000 


000000 
000 000 








1 

! 










*** DUPLICATE 


THROUGH 000236 *** 


















000240 


000000 
000 000 


000000 
000 000 


001110 
110 002 


000000 
000 000 


. 




NX 


! 
! 




H 


, 




00250 


001454 
054 003 


000264 
264 000 


000000 
000 000 


000000 
000 000 


. TL 


DT 




! 


4 




! 




000260 


000001 
001 000 


001612 
212 003 


074360 
360 170 


003413 
013 007 


. A 


V2 


SN 


AEC! 

! 




px 


! 




00270 


063014 
014 146 


131574 
174 263 


000000 
000 000 


000000 
000 000 


.PMD 






! 
J f 


3 




1 




000300 


001051 


000001 


000045 


050114 


! M3 


A 


7 


L36! 












051 002 


001 000 


045 000 


114 120 








!) 




% 


LP! 




000310 


000000 
000 000 


000001 
001 000 


000100 
100 000 


000304 
304 000 




A 


AX 


D6! 

! 




@ 


D ! 




000320 


000524 
124 001 


000000 
000 000 


000000 
000 000 


000000 
000 000 


. HT 






! 
!T 






! 




000330 


000000 
000 000 


000000 
000 000 


000000 
000 000 


063014 
014 146 


! 






PMD! 

! 






f ! 




000340 


131574 


047123 


052120 


052123 


!... 


LUK 


MSX 


MS$! 












174 263 


123 116 


120 124 


123 124 








! 3 


SN 


PT 


ST! 




000350 


000000 


016746 


177734 


012746 


1 


DIN 


7T 


CTF! 












000 000 


346 035 


334 377 


346 025 








! 


f 


\ 


f ! 




000360 


001037 
037 002 


104377 
377 210 


103456 
056 207 


005046 
046 012 


! MW 


U61 


UYF 


AX8! 

! 




• 


& ! 

ZK- 


187/2-81 
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O Type of dump: Postmortem or snapshot. If it is a snapshot 
dump, the dump identification is printed. 

The name of the task being dumped, and the date and time the 
dump was generated. 

© The program counter at the time of the dump. If it is a 
Postmortem Dump, the reason the task was aborted is printed. 

Q The general registers, stack pointer, and processor status at 
the time of the dump. 

© The task status flags at the time of the dump. See the 
description of ATL or TAL in the RSX-llM/M-PLUS MCR 
Operations Manual for the meaning of the flags. 

© The task event flag mask word at the time of the dump. If 
the dump is a snapshot dump, the efn specified in the SNAP$ 
macro will be ON (see Section D.2.2). 

O The task UIC and the current value of the directive status 
word . 

© The task's priority and default priority, number of 
outstanding I/O requests, and the terminal from which the 
task was initiated (TI:). 

© The task load device and the logical block number for the 
start of the task image on the device. 

(B The floating-point unit (FPU) registers or the extended 
arithmetic element (EAE) registers if the task is using one 
of these hardware features. If the task is not using the FPU 
or EAE, these registers are not printed. If the task uses 
the FPU and does not specify /FP on the task image file, or 
if it uses the EAE unit and has not specified the /EA switch, 
the registers are not printed. If the machine you are using 
has both an FPU and an EAE, PMD assumes you are using the FPU 
because it is the unit of choice for arithmetic computations. 

© The logical unit assignments at the time of the dump. UNIT 
is the logical unit number, and DEVICE is the device to which 
the logical unit is assigned. For snapshot dumps, the file 
names of any open files are displayed under FILE STATUS. 
Postmortem Dumps do not display this information because all 
of the files have been closed as a result of the I/O rundown 
on the aborted task. 

® The following are displayed: the overlay segments loaded and 
resident libraries mapped at the time of the dump; the 
relative block number of the segment; the base address; the 
length of the segment; and, for tasks using manual load, the 
segment names. For resident libraries, the library name is 
also displayed. The block number can be used to determine 
which segment is loaded, by reference to the memory 
allocation file generated by the Task Builder. The starting 
block number for each segment is the relative block number of 
the segment. By obtaining a match, you can determine the 
name of the segment in memory. Zero-length segments are 
usually co-tree roots. 
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® The task stack at the time of the dump. The address is 
displayed, along with the contents, in octal, ASCII, and 
Radix-50. Each word on the stack is dumped. If the stack 
pointer is above the initial value of the stack (H.ISP), only 
one word is dumped. The rest is dumped as part of the task 
image. 

<D The task image itself. The partition being dumped and the 
limits of interest are displayed. For Postmortem Dumps, all 
address windows in use are dumped. For snapshot dumps, the 
virtual task limits that you request are displayed. The dump 
routine rounds the requested low limit down to the nearest 
multiple of eight bytes and rounds the requested high limit 
up to the nearest multiple of eight bytes. The dump image 
displays the virtual starting address of a 4-word block of 
memory, the data in both octal and Radix-50 on the first 
line, and byte octal and ASCII on the second line. A 4-word 
block that is repeated in a contiguous region of memory is 
printed once, and then noted by the message 

*** DUPLICATE THROUGH xxxxxx *** 

where xxxxxx indicates the last word that is duplicated. If 
the task was aborted, all address windows in use are dumped. 
If the dump is a snapshot dump, up to four contiguous blocks 
of memory can be dumped, if requested. 



D.2 SNAPSHOT DUMP 

Snapshot dumps are edited dumps produced for running tasks. You can 
request a snapshot dump any number of times during the execution of a 
task. The information generated is under the control of the 
programmer . 

Snapshot dumps are generated by the following macros: 

• SNPDF$ — Defines offsets in the snapshot dump control block 
and defines control bits, which control the format of the dump 

• SNPBK$ — Allocates the snapshot dump control block (see Table 
D-1) 

• SNAP$ — Causes a snapshot dump to be generated 

SNPBK$ and SNAP$ issue calls to SNPDF$; so, you need not explicitly 
issue the SNPDF$ macro call. Sections D.2.1 and D.2. 2 describe the 
SNPBK$ macro and the SNAP$ macro, respectively. 
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(LI) 
(HI) 
(L2) 
(H2) 
(L3) 
(H3) 
(L4) 
(H4) 




2 

4 

6 

10 

12 

14 

16 

20 

22 

24 

26 

30 

32 

34 






SB.CTL 


CONTROL FLAGS 


SB.DEV 


DEVICE MNEMONIC 


SB.UNT 


UNIT NUMBER 


SB.EFN 


EVENT FLAG 


SB.ID 


SNAP IDENTIFICATION 


SB.LMI 


MEMORY BLOCK 


1 




LIMITS 




MEMORY BLOCK 


2 




LIMITS 




MEMORY BLOCK 


3 




LIMITS 




MFMORY BLOCK 


4 




LIMITS 


SB.PMD 


"PMD " 




IN RADIX-50 






ZK-4 88-81 



Figure D-1 Snapshot Dump Control Block Format 

D.2.1 Format of the SNPBK$ Macro 

The format of the SNPBK$ macro call is: 

SNPBK$ dev,unit,ctl,efn,id,Ll,Hl,L2,H2,L3,H3,L4,H4 



dev 



The 2-character ASCII name of the device to which the dump is 
directed. If it is a directory device, the UFD [1,4] must be on 
the volume. The dump is written to the disk and then spooled to 
the line printer. If there is no print spooler, the file is left 
on the disk. If the device is not a directory device, the dump 
goes directly to the device. 



unit 



ctl 



The unit number of the device to which the dump is directed, 



The set of flags that control the format of the dump and the data 

to be printed. The flags are: 

SC.HDR Print the dump header (items 3 to 10 in Figure 
D-1). Items 1 and 2 are always printed. 

SC.LUN Print information on all assigned LUNs (item 11) . 

SC.OVL Print information about all loaded overlay segments 

(item 12) . 



D-6 



efn 



id 



MEMORY DDMPS 



SC.STK Print the user stack (item 13) . 

SC.WRD Print the requested memory in octal words and 
Radix-50 (item 14) . 

SC.BYT Print the requested memory in octal bytes and ASCII 
(item 14) . 



The event flag to be used to synchronize your program and PMD. 



A number that identifies the snapshot dump. Because dumps can be 
requested at different times and under different conditions, this 
ID is used to identify the place or reason for the dump. 

L1,L2,L3,L4 

The starting addresses of the memory blocks to be dumped. 
H1,H2,H3,H4 

The ending addresses of the memory blocks to be dumped. 

NOTE 

If no memory is to be dumped, each limit 
(L1,L2,L3,L4,H1,H2,H3,H4) should be 0. 

Only one snapshot dump control block is allowed. It generates the 
global label ..SPBK, 

NOTE 

Because SNPBK$ is used to allocate 
storage for the snapshot dump control 
block, all arguments except dev must be 
valid arguments for .WORD or .BYTE 
directives. 



D.2.2 Format of the SNAP$ Macro 

The format of the SNAP$ macro is: 

SNAP$ ctl,efn,id,Ll,Hl,L2,H2,L3,H3,L4,H4 



ctl 



The set of flags that control the format of the dump and the data 
to be printed. The flags are: 

SC.HDR Print the dump header. 

SC.LUN Print information on all assigned LUNs . 

SC.STK Print the user stack. 

SC.OVL Print information about all loaded overlay 
segments. 
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SC.WRD Print the requested memory in octal words and 
Radix-50. 

SC.BYT Print the requested memory in octal bytes and 
ASCII. 



The event flag to be used to synchronize your program and PMD. A 
Wait-For-Single-Event-Flag directive is always generated to 
perform synchronization. 



id 



A number that identifies the snapshot dump. Because dumps can be 
requested at different times and under different conditions, this 
ID is used to identify the place or reason for the dump. 

L1,L2,L3,L4 

The starting addresses of memory blocks to be dumped. 
H1,H2,H3,H4 

The ending addresses of memory blocks to be dumped. 

NOTES 

1. If no memory is to be dumped, each limit 
(L1,L2,L3,L4,H1,H2,H3,H4) should be 0. 

2. You can set the control flags in any 
combination; they are not mutually 
exclusive. Thus, any number of options can 
be obtained; for example, 
SC.HDRiSC.LUN I SC.WRD prints the header, 
LUNs, and the requested memory in word octal 
and Radix-50 mode. 

3. Arguments should be specified only to 
override the information already in the 
snapshot dump control block. 

4. Because SNAP$ generates instructions to move 
data into the snapshot dump control block, 
its arguments must be valid source operands 
for MOV instructions. 



D.2.3 Example of a Snapshot Dump 

The sample program shown in Example D-2 causes two snapshot dumps to 
be printed directly on LPO:. The first dump uses the parameters 
defined in the snapshot dump control block. The header is generated, 
and the data in relative locations BLK to BLK+220 is displayed, in 
word octal and Radix-50. The identification on the dump is 1. 

The second dump causes the data in the locations BLK to BLK+220 to be 

displayed in byte octal and ASCII. A header is also generated. The 

dump identification is 64 (100 octal) . Figures D-3 and D-4 show the 
dumps generated by the sample program. 
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SNPTST - TEST SNAP DUMP AND PMD MACRO MIOIO 03-SEP-76 15:57 PAGE 1 



1 
2 
3 

4 000000 

5 000036 
000041 
000044 

6 

7 000046 

8 000216 

9 000222 

10 000226 

11 000412 
12 



123 
124 
000 



116 
123 



BLK: 
120 BUF: 
124 



START: 



012700 000036' 



000004 
000046' 



•TITLE SNPTST - TEST SNAP DUMP AND PMD 

.IDENT /Ol/ 

.MCALL SNPBK$,SNAP$,CALL 

SNPBK$ LP,0,SC.HDRiSC.OVL!SC.WRD,l,l,BLK,BLK+2 2 

.ASCIZ /SNPTST/ 



.EVEN 

SNAP$ 

MOV 

CALL 

SNAP$ 

lOT 

.END 



#BUF,RO 

$CAT5 

#SC.HDR!SC.OVL!SC.BYT, ,#100 

START 



O 
I 

IX) 



SNPTST - TEST SNAP DUMP AND PMD MACRO MlOlO 
SYMBOL TABLE 



SB.EFN= 000006 
SB. ID = 000010 
SB.LM1= 000012 
SB.PMD= 000032 
SB.UNT= 000004 



BLK OOOOOOR 
BUF 000036R 
IE.ACT= ****** GX 
SB.CTL= 000000 
SB.DEV= 000002 




. ABS. 000000 
000414 
ERRORS DETECTED: 


000 
001 




03-SEP-76 15:57 PAGE 1-1 



SC.BYT= 000040 
SC,HDR= 000001 
SC.LUN= 000002 
SC.OVL= 000004 



SC.STK= 000010 
SC.WRD= 000020 
START 000046R 
$CAT5 = ****** GX 







3 

n 
3: 
o 
w 


$DSW = 


****** GX 


^4 


$$$T2 = 
. .SPBK 


000027 
OOOOOORG 


a 


...SNP= 


000032 


•0 
0) 



VIRTUAL MEMORY USED: 1335 WORDS ( 6 PAGES) 
DYNAMIC MEMORY AVAILABLE FOR 30 PAGES 
ASSEMBLY TIME (ELAPSED): 00:00:14 
SNPTST, SNPTST=SNPTST 



Example D-2 Sample Program That Calls for Snapshot Dumps 
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Example D-3 Sample Snapshot Dump (in Word Octal and Radix-50) 



TIME: 5-OCT-76 15:06 



Rl - 100104 
R5 - 000000 



R2 - 000000 
SP - 000304 



R3 
PS 



140130 
170000 



SNAPSHOT DUMP ID: 1 

TASK: TT6 

PC: 000522 

REGS: RO - 000000 

R4 - 000000 

TASK STATUS: MSG -CHK STP WFR REM MCR 

EVENT FLAG MASK FOR 1-16> 000001 

CURRENT OIC: [007,001] DSW: 1. 

PRIORITY: DEFAULT - 50. RUNNING - 50. 

LOAD DEVICE - DBO: LBN: 1,160034 

FLOATING POINT UNIT 

STATUS - 000000 

RO - 000000 000000 000000 000000 

Rl - 000000 000000 000000 000000 

R2 - 000000 000000 000000 000000 

R3 - 000000 000000 000000 000000 

R4 - 000000 000000 000000 000000 

R5 - 000000 000000 000000 000000 

OVERLAY SEGMENTS LOADED AND RESIDENT LIBRARIES MAPPED 

STARTING RELATIVE BLOCK: 000002 BASE: 000000 LENGTH: 001454 



I/O COUNT: 0. TI DEVICE - TT6: 







TASK 


IMAGE 












PARTITION: 


GEN 


VIRTUAL 


LIMITS: 


)00304 - 


000524 


000300 


001051 


000001 


000025 


050114 


M3 


A 


U 


L36! 


000310 


000000 


000001 


000001 


000304 




A 


A 


D6! 


000320 


000524 


000000 


000000 


000000 


HT 








000330 


000000 


000000 


000000 


063014 








PMD! 


000340 


131574 


047123 


052120 


052123 


• • • 


LUK 


MSX 


MS$! 


000350 


000000 


016746 


177734 


012746 




DIN 


7T 


CTF! 


000360 


001037 


104377 


103456 


005046 


MW 


U61 


UYF 


AX8! 


000370 


012746 


000304 


012746 


000336 


CTF 


D6 


CTF 


EV! 


000400 


017646 


000000 


062766 


000002 


EBV 




PLV 


B! 


000410 


000002 


017666 


000002 


000002 


B 


EB8 


B 


B! 


000420 


012746 


0002507 


104377 


013435 


CTF 


31 


U61 


UX/ ! 


000430 


005046 


005046 


005046 


005046 


AX8 


AX8 


AX8 


AX8! 


000440 


012746 


000336 


017646 


000000 


CTF 


EV 


EBV 


1 


000450 


062766 


000002 


000002 


017666 


PLV 


B 


B 


EB8! 


000460 


000002 


000002 


012746 


003413 


B 


B 


CTF 


AEC! 


000470 


104377 


103006 


022737 


177771 


U61 


UQO 


FBO 


81! 


000500 


000046 


001402 


000261 


000405 


8 


SJ 


DQ 


FU! 


000510 


016746 


177576 


012746 


001051 


DIN 


5F 


CTF 


M3! 


000520 


104377 


012700 


000342 


004767 


U61 


CSH 


EZ 


AWl! 
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Example D-4 Sample Snapshot Dump (in Byte Octal and ASCII) 

SNAPSHOT DUMP ID: 64 
TASK: TT6 TIME: 5-OCT-76 15:06 

PC: 000716 

REGS: RO - 000345 Rl - 074400 R2 - 000120 R3 - 140130 
R4 - 000000 R5 - 000000 SP - 000304 PS - 170000 
TASK STATUS: MSG -CHK STP WFR REM MCR 
EVENT FLAG MASK FOR 1-16> 000001 
CURRENT UIC: [007001] DSW: 1. 

PRIORITY: DEFAULT - 50. RUNNING - 50- I/O COUNT: 0. TI DEVICE - TT6: 
LOAD DEVICE - DBO: LBN: 1,160034 

FLOATING POINT UNIT 

STATUS - 000000 

RO - 000000 000000 000000 000000 

Rl - 000000 000000 000000 000000 

R2 - 000000 000000 000000 000000 

R3 - 000000 000000 000000 000000 

R4 - 000000 000000 000000 000000 

R5 - 000000 000000 000000 000000 

OVERLAY SEGMENTS LOADED AND RESIDENT LIBRARIES MAPPED 

STARTING RELATIVE BLOCK: 000002 BASE: 000000 LENGTH: 001454 
STARTING RELATIVE BLOCK: 000004 BASE: 001454 LENGTH: 000264 

(continued on next page) 
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Example D-4 (Cont.) Sample Snapshot Dump (in Byte Octal and ASCII) 









TASK 


IMAGE 














PARTITION: 


GEN 


VIRTUAL 


LIMITS: 000304 


- 000524 


000300 


051 


002 


001 000 


045 


000 


114 


120 


!) 




% 


LP 


000310 


000 


000 


001 000 


100 


000 


304 


000 


1 




@ 


D 


000320 


124 


001 


000 000 


000 


000 


000 


000 


!T 








000330 


000 


000 


000 000 


000 


000 


014 


146 


! 






f 


000340 


174 


263 


123 116 


120 


124 


123 


124 


! 3 


SN 


PT 


ST 


000350 


000 


000 


346 035 


334 


377 


346 


025 


1 


f 


\ 


f 


000360 


037 


002 


377 210 


056 


207 


046 


012 


; 






& 


000370 


346 


025 


304 000 


346 


025 


336 


000 


if 


D 


f 


^ 


000400 


246 


037 


000 000 


366 


145 


002 


000 


<& 




ve 




000410 


002 


000 


266 037 


002 


000 


002 


000 


! 


6 






000420 


346 


025 


107 005 


377 


210 


035 


207 


.£ 


G 






000430 


046 


012 


046 012 


046 


012 


046 


012 


I& 


& 


& 


& 


000440 


346 


025 


336 000 


246 


037 


000 


000 


.f 




& 




000450 


366 


145 


002 000 


002 


000 


266 


037 


.ve 






6 


000460 


002 


000 


002 000 


346 


025 


013 


007 






f 




000470 


377 


210 


006 206 


337 


045 


371 


377 






% 


y 


000500 


046 


000 


002 003 


261 


000 


005 


001 


& 




T 




000510 


346 


035 


176 377 


346 


025 


051 


002 


f 




f 


) 


000520 


377 


210 


300 025 


342 


000 


367 


Oil 




@ 


b 


w 
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APPENDIX E 
RESERVED SYMBOLS 



Several global symbols and program section names-*- are reserved for use 
by TKB.2 Special handling occurs when TKB encounters a definition of 
one of these names in a task image. 

The definition of a reserved global symbol in the root segment causes 

a word in the task image to be modified with a value calculated by 

TKB. The relocated value of the symbol is taken as the modification 
address. 

The following global symbols are reserved by TKB: 

Global Modification 

Symbol Value 

.FSRPT Address of file storage region work area (.FSRCB). 

.MBLUN Mailbox logical unit number. 

.MOLUN Error message output device. 

.NLUNS The number of logical units used by the task, not 
including the message output and overlay units. 

•NOVLY The overlay logical unit number. 

N.OVPT Address of overlay run-time system work area {.NOVLY). 

.NSTBL The address of the segment description tables. This 
location is modified only when the number of segments 
is greater than one. 

.ODTLl Logical unit number for the ODT terminal device TI : . 

.0DTL2 Logical unit number for the ODT line printer device 
CL: . 



1. In RSX-llM and FSX-llM-PLUS, absolute sections (ASECTs) and both 
blank and named control sections {CSECTs) are supplanted by program 
sections (PSECTs) . The .PSECT assembler directive eliminates the need 
for .ASECT and .CSECT directives, except for compatibility with other 
systems. This manual refers to all sections as program sections, 
unless the specific characteristics of ASECTs or CSECTs apply. 

2. All symbols and program section names containing a period (.) or a 
dollar sign ($) are reserved for DIGITAL-supplied software. 
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Global Modification 

Symbol Value 

.SUMLl P/OS Standard utility module LUN. 

•PTLUN Logical unit number for plotter/graphics software. 

$OTSV Address of Object Time System work area ($OTSVA) . 

•TRLUN The trace subroutine output logical unit number. 

.USLUl Logical unit number for special purpose user software. 

.USLU2 Logical unit number for special purpose user software. 

$VEXT Address of vector extension area ($VEXTA) . 

TKB reserves the following program section names. In some cases, the 
definition of a reserved program section causes that program section 
to be extended if you specify the appropriate option. 



Source 
Location 

TKB 



TKB. 



TKB 



TKB 



TKB 



Input 
Module 



Section 
Name 

$$ALER 



>$ALVC 
iS|$ALVD 
$SALV1 

$$AUTO 



$$DBTS 



Description 

Contains code to process or trap Overlay Run-time 
System segment load errors. Provides named areas 
in the task for the FORTRAN-IV Object Time System 
and the RSX-llM Overlay Run-time System. 

Contains the segment autoload vectors for tasks 
without I- and D-space. 

Contains the D-space portions of the segment 
autoload" vectors in an I- and D-'space task. 

Contains the I-space portions of the segment 
autoload vectors in an I- and D-space task. 

Contains code to determine if a called subroutine 
in an overlay segment is already in memory or if 
that overlay segment should be read into memory 
before control is passed to the subroutine that is 
called. 

This symbol should appear in the debugger input 
module with the symbol $DBTS as follows: 



$DBTS: 



.PSECT $$DBTS 
.PSECT 



SYSLIB 



$$DEVT 



The task builder extends $$DBTS and fills it with 
time stamp information followed by the filename 
information of the .STB file. 

The extension length (in bytes) is calculated from 
the formula : 



EXT 



<S.FDB+52>*UNITS 



The definition of S.FDB is obtained from the root 
segment symbol table, and UNITS is the number of 
logical units used by the task, excluding the 
message output, overlay, and ODT units. 
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Source 
Location 

SYSLIB 



SYSLIB 



TKB 



Section 
Name 

$$FSR1 
$$I0B1 
$$1082 



TKB 
TKB 



$$LOAD 
$$MRKS 



SYSLIB 



TKB 



$$0BF1 



$$0BF2 



TKB 



$$OVDT 



TKB 



$$OVRS 



TKB 
TKB 

TKB 
TKB 



$$PDLS 
$$RDSG 

$$RGDS 
$$RTQ 



Description 

The extension of this section is specified by the 
ACTFIL option. 

The extension of this option is specified by the 
MAXBUF option. 

A zero length .PSECT containing a label, lOBFND, 
that is stored in the work area offset, W.BEND, 
representing the upper bound of the I/O buffer, 
$$I0B1. TKB uses $$I0B2 as a boundary value to 
determine whether the I/O buffer has overflowed. 

Overlay manual load routine. 

Contains code to properly mark those segments that 
are not needed any longer or have been overlaid by 
another segment as being out of memory. This 
ensures that a fresh copy of the overlay segment 
will be read in the next time the overlay segment 
is needed. 

FORTRAN OTS uses this area to parse array type 
format specifications. This section can be 
extended by the FMTBUF keyword. 

A zero length .PSECT containing a label, OBFH, 
that is stored in the work area offset, W.OBFH, 
which represents the upper bound of the run-time 
format buffer, $$0BF1. TKB uses $$0BF2 to 
determine whether the run-time format buffer has 
overflowed. 

The Overlay Run-time System impure data area. The 
symbol .NOVPT in low memory points to this area. 
This area defines the operational parameters with 
which the Overlay Run-time System operates on 
disk-resident and memory-resident overlay 
structures. 



The .ABS. program section that redef 
Overlay Run-time System impure data 
different symbols, defined as offsets and 
to zero. These offsets are necessary f 
linkages between the subroutines in the 
Run-time System. This program section 
included in the memory allocation of 
because of its absolute program section a 

Cluster library service routine. 



ines the 
area with 

relative 

or proper 

Overlay 

is never 
the task 
ttribute. 



Contains the code that reads into memory the 
overlay segment selected by the code contained in 
the programs section $$AUTO. 

Contains the region descriptors for resident 



libraries r 



ef erred to by the task. 



Defines the PSECT used for selective enabling of 
AST recognition in the Overlay Run-time System. 
$$RTQ is in length if $AUTOT is not included. 
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Source 
Location 

TKB 



TKB 
TKB 

TKB 

TKB 
TKB 

FORTRAN 



Section 
Name 

$$RTR 



$$RTS 
$.<!SLVC 

$$SGDO 

$$SGD1 
$$SGD2 



Description 

Defines the PSECT used for selective disabling of 
AST recognition in the Overlay Run-time System. 
$$RTR is in length if $AUTOT is not included. 



Contains the return instruction. 

Supervisor-mode library transfec 
(RSX-llM-PLUS only) . 



vectors 



Contains the program section adjoining the task 
segment descriptors. 

Contains the task segment descriptors. 

Contains a .WORD following the task segment 
descriptors . 



TKB 



$$TSKP TKB fills in the following words in the PSECT: 

• APR bit map in word $APRMP 

• Task offset into region in word $LBOFF 

• Maximum physical read/write memory needed for 
task in word $MXLGH 

• Maximum physical read-only memory needed for 
task in word $MXLGH+2 

• Task extension in 32-word blocks in word $LBEXT 
$$WNDS Contains task window descriptors 
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APPENDIX F 
IMPROVING TASK BOILDER PERFORMANCE 



This appendix contains procedures to assist you in maximizing Task 
Builder (TKB) performance. These procedures include: 

• Evaluating and improving TKB throughput 

• Modifying command switch defaults to provide a more efficient 
user interface 

• Using the Slow Task Builder when large work file space is 
required 

These procedures assume that the program to be linked requires 
features not found in the Fast Task Builder (FTB) described in 
Appendix G. 

Using the procedures described in this appendix may require relinking 
TKB. You can do this only in a system that has, as a minimum, a 14K 
user-controlled or system-controlled partition. In some cases, you 
can make the modifications without relinking by using the binary patch 
program ZAP (see the RSX-11 Utilities Manual ) . 

Modifications to the TKB build file imply one or more of the following 
files located under UFD [1,24] (mapped) or [1,20] (unmapped): 

RSX-llM systems: 

TKBBLD.CMD 
STKBLD.CMD 

RSX-llM-PLUS systems: 

TKBBLD.CMD 
STKBLD.CMD 

These files reside on the disk containing the utility object files. 



F.l EVALUATING AND IMPROVING TASK BOILDER THROUGHPUT 

Task Builder throughput is determined by three factors: 

• The amount of disk latency incurred because of overlays 

• The amount of memory available for table storage 

• The amount of disk latency due to input file processing 

The following sections outline methods for improving throughput in 
each of these last two cases. 
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F.1.1 Table Storage 

The principal factor governing TKB performance is the amount of memory 
available for table storage. To reduce memory requirements, a work 
file is used to store symbol definitions and other tables. This work 
file cannot exceed 65,543 bytes. As long as the size of these tables 
is within the limits of available memory, the contents of this file 
are kept in memory and the disk is not accessed. If the tables exceed 
this limit, some information must be displaced and moved to the disk, 
degrading performance accordingly. 

You can gauge work file performance by consulting the statistics 
portion of the TKB map. The map displays the following parameters: 

• Number of work file references — Total number of times that 
work file data was referred to. 

• Work file reads — Number of work file references that 
resulted in disk accesses to read work file data. 

• Work file writes — Number of work file references that 
resulted in disk accesses to write work file data. 

• Size of core pool — Amount of in-core table storage in words. 
This value is also expressed in units of 256-word pages 
(information is read from and written to disk in blocks of 256 

words) . 

• Size of work file — Amount of work file storage in words. If 
this value is less than the pool size, the number of work file 
reads and writes is 0. That is, no work file pages are 
removed to the disk. This value is also expressed in pages 
(256-word blocks) . 

• Elapsed time — Amount of time required to build the task 
image and output the map. This value excludes DDL processing, 
option processing, and the time required to produce the global 
cross-reference. 

You can reduce the overhead for gaining access to the work file in one 
or more of the following ways: 

• By increasing the amount of memory available for table storage 

• By placing the work file on the fastest random access device 

• By decreasing system overhead required to gain access to the 
file 

• By reducing the number of work file references 

You can increase the amount of table storage by installing TKB in a 
larger partition or, if TKB is running in a system-controlled 
partition, by using the INSTALL/INC keyword to allocate more space. 

In a system that includes support for the Extend Task directive, TKB 
automatically increases its size if it is checkpointable and installed 
in a system-controlled partition. You set the maximum limit. You can 
increase this maximum by issuing the MCR command SET /MAXEXT. 

Increasing the proportion of resident dynamic memory reduces the 
amount of I/O necessary for access to TKB internal data structures. 
As stated above, once the resident memory has been filled, the data 
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to the work file logical unit number. This logical unit number 
(W$KLUN) is specified in the build command file. Preferably, this 
unit number should be assigned to a device other than the system 
device, for example a fixed-head disk. 



Displacement of pages to the work fi 
used basis. The work file extends 
all pages displaced. The parameter 
command file of TKB and defines 
negative value indicates that the ex 
value indicates that the extend is c 
fails, a noncontiguous request is 
extend fails, a fatal work file I/O 
work file remains contiguous, a high 



le is done on a least recently 
automatically as necessary to hold 
W$KEXT is provided in the build 

the file extension properties. A 
tend is noncontiguous; a positive 
ontiguous. If a contiguous extend 

attempted; if a noncontiguous 
error is reported. As long as the 
er access rate can be obtained. 



It is not possible to state exactly how many symbols TKB can process, 
because there are many data structures included in virtual memory. 
The following is a list of the structures that are stored in the 
virtual memory. All the sizes given are approximate only (sizes vary 
with characteristics of the task being built and may vary from release 
to release) . 



Structure Name 



Segment Descriptor 



Description 



Approximate Size 
(in Words) 



P-section Descriptor 



Symbol Descriptor 



Contains listhead 80, 
sizes, the pointers 
defining the overlay 
tree, the segment name. 
Part of this structure 
becomes the segment 
descriptor in the 
resultant task image. 

Contains the name, 10, 
address size, and 
attributes of a 
p-section. 



Element Descriptor 



Control Section 
Mapping Table 



Contains symbol name, 
value, flags, and 
pointers to defining 
segment and program 
section descriptors. 

Contains module 
name, ident , filename, 
count of program 
section and some 
flags. 

Table of program 
section size and 
program section 
descriptor addresses. 



8. (nonoverlaid task) 
15. (overlaid task) 

8.-18. 



Two words per 
program section in 

each module 



The maximum usage of virtual memory occurs during phase three of TKB, 
when the symbol table is built. However, phase one makes significant 
use of virtual memory when an overlaid task is being built. It is at 
this point that all the segment descriptors are allocated, as well as 
an element descriptor for every file name encountered during the 
parsing of the tree description. In addition, a p-section descriptor 
is produced for every .P3ECT directive encountered in the overlay 
description. 
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The parsing of the overlay description also makes use of dynamic 
memory during the processing of each directive. This memory is 
released upon completion of the analysis; during the analysis, 
however, the whole tree description must fit into the resident portion 
of the storage. If sufficient storage cannot be obtained in the 
resident dynamic memory, the error message NO DYNAMIC STORAGE 
AVAILABLE is returned. The method for increasing the ratio of dynamic 
storage to virtual memory can be applied here, possibly to allow a 
task with a large overlay description to be built. 

The amount of memory required during analysis depends on: 

• The number of directives 

• The length of .FCTR lines 

• The number of operators, that is, commas, dashes, and 
parentheses) 

• The number of file names encountered 

TKB links all DEC-supplied tasks in a 14K partition. 

There are a number of ways to reduce the amount of virtual memory 
required during the build of a specific task. Reducing the data 
structures in virtual memory also increases the speed of searching the 
tables and reduces the amount of paging to the work file. 

1. Extract object modules by name from relocatable object 
libraries (for example., LIBRY/LB:M0D1:M0D2) . This technique 
requires smaller element descriptors and fewer file name 
descriptors and is also faster because there are fewer files 
to open and close. 

2. Use concatenated object modules for the same reasons as 
above. 

3. Use shared regions (resident libraries and common areas) for 
language and overlay run-time systems and file control 
services. Such use of shared regions allows symbols and 
p-sections to be defined only once, rather than on multiple 
branches of the tree. 

4. Place modules that occur on parallel branches of the tree in 
a common segment (for example, closer to root) for the same 
reasons as in 3 above. 

5. Use the /SS switch on symbol table files (.STB) that describe 
absolute symbol definitions so that only those symbols 
referenced are extracted from the module. 

6. Minimize the number of segments and keep the tree balanced. 
For example, if one segment is very long, there is no value 
in putting a tree structure in parallel unless creating one 
segment in parallel would be longer. 

In addition to the above, a version of TKB can be built which has less 
throughput but requires less virtual memory per element than TKB. 
This version is built using the command file STKBLD.CMD supplied on 
the RK05 utility disk, or the RK06 and RP system disks under UFD 
[1,20] (unmapped) or [1,24] (mapped). 
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There are four error messages associated with the virtual memory 
system: 

• NO DYNAMIC STORAGE AVAILABLE. This error occurs when there is 
insufficient resident storage for creating some data 
structures. As much as possible of the data already allocated 
(all unlocked pages) has been paged to the work file, but 
there is still not enough free memory. Such a situation might 
arise during the analysis of the overlay description, early in 
the task-build run, and particularly if it is a complex tree. 
Reducing the ODL and extending the Task Builder memory 
allocation (see above) are the recommended recovery 
procedures. 

• UNABLE TO OPEN WORKFILE. The probable causes of this error 
are: 

Device assigned to logical unit 8 of the Task Builder is 
not mounted. 

- The device is not FILES-11. 
There is no space on the volume. 

- The device is off line, not ready, write locked, or faulty. 

- There is no such device. 

The MCR function LUN ...TKB may be used to determine which 
device the Task Builder is attempting to use. 

• WORKFILE I/O ERROR. The probable causes of this error are: 

Hardware error (for example, parity error on the disk) . 
Device is not ready, or is write-locked . 

- An extend failure has occurred (for example, the disk is 
full) . 

• NO VIRTUAL MEMORY STORAGE AVAILABLE. The addressable limit of 
the virtual memory has been reached. There is no recovery 
other than to reduce the virtual memory requirements of the 
task being built along the lines suggested earlier. 

The work file normally resides on the device from which TKB was 
installed. You can change the device by reassigning logical unit 8 
through the Monitor Console Routine or by editing the build file and 
relinking TKB. 

System overhead for work file accesses is incurred in translating a 
relative block number in the file to a physical disk address. To 
minimize this overhead, TKB requests disk space in contiguous 
increments. The size of each increment is equal to the value of 
symbol W$KEXT defined in TKB build file. A larger positive value 
causes the file to be extended in larger contiguous increments and 
reduces the overhead required to gain access to the file. The 
increment should be set to a reasonable value because TKB resorts to 
noncontiguous allocation whenever contiguous allocation fails. ; .b 
You can reduce the size of the work file by: 

• Linking your task to a core-resident library containing 
commonly used routines (for example, FORTRAN Object Time 
System) whenever possible 
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• Including common modules, such as components of an object time 
system, in the root segment of an overlaid task 

• Using an object library or file of concatenated object modules 
if many modules are to be linked 

When you use either of the last two procedures, system overhead is 
also significantly reduced because fewer files must be opened to 
process the same number of modules. 

You can reduce the number of work file references by eliminating 
unneeded output files and cross-reference processing, or by obtaining 
the short map. In addition, you can usually exclude selected files, 
such as the default system object module library, from the map. In 
this case you can obtain, and retain, a full map at less frequent 
intervals. 



F.1.2 Input File Processing 

The procedures for minimizing the size of the work file and number of 
work file accesses also drastically reduce the amount of input file 
processing. 

A given module can be read up to four times when the task is built: 

• To build the symbol table 

• To produce the task image 

• To produce the long map 

• To produce the global cross-reference 

Files that are excluded from the long map are read only twice. The 
third and fourth passes are eliminated for all modules when you 
request a short map without a global cross reference. 



F.1.3 Summary 

In summary, you can use the following procedures to improve TKB 
throughput: 

• Use the INSTALL/INC or EXTTSK keyword to allocate more table 
space. 

• Increase maximum task size by raising the system limit for 
dynamic task extension. 

• Reduce disk latency by placing the work file on the fastest 
random access device. 

• Reduce system overhead by modifying the command file to 
allocate work file space in larger contiguous increments. 

• Decrease work file size by using resident libraries, 
concatenated object files, and object libraries. 
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• Decrease work file size by including common modules into the 
root segment of an overlaid task. 

• Decrease the number of work file references by eliminating the 
map and global cross-reference, obtaining the short map, or 
excluding files from the map. 



F.2 MODIFYING COMMAND SWITCH DEFAULTS 

The default switch settings and values provided by the Task Builder as 
released may not suit the requirements of all installations. For 
example, the default /-EA (no KEll Extended Arithmetic Element) would 
be unsatisfactory at an installation that made frequent use of this 
hardware. 

You can thus tailor the switch defaults by altering the contents of 
the words that contain initial switch states. Modifying TKB in this 
way is a 3-step process: 

1. Consult Tables F-1 through F-4 to determine the switch word 
and bit to be altered. 

2. Edit the appropriate TKB command file to include the switch 
word modification through a GBLPAT keyword referring to the 
global switch word name. 

3. Relink TKB using the modified command file. 

The command files for system tasks, as provided with the released 
system, require the standard set of TKB defaults; therefore, you must 
retain and use an unmodified copy of TKB whenever such tasks are 
relinked. 

You use Tables F-1 through F-4 to alter the defaults as follows: 

1. You identify the switch and the file to which it applies. 

2. You consult the switch category entry in each table to locate 
the applicable switch words. 

3. You look at the switch settings to find the switch and 
associated bit. 

4. You specify the revised value and switch word as arguments in 
a GBLPAT keyword. 

5. You relink TKB to produce a version containing the 
appropriate defaults. 

For example, to change the TKB Extended Arithmetic Element default to 
/EA, perform the steps described below. 

By consulting Table F-1, you determine that two switch words, $DFSWT 
and $DFTSK, contain task file switches. Of these, $DFTSK contains the 
default setting for the /EA switch in bit 13. Setting this bit to 1 
changes the initial switch setting to /EA. This new value is combined 
with the initial contents to yield the revised setting 120002. The 
required keyword input is: 

TKB>GBLPAT=TASKB:$DFTSK: 120002 
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NOTE 

The setting of bit positions not listed 
in the tables must not be altered. 

The only switches that have associated values are /AC and /PR. In 
these cases, the value is the number of the initial APR used to map 
the task. You can alter the default by changing the value of the 
GBLDEF keyword for the symbol D$FAPR in TKB build file. Only values 4 
or 5 can be used . 



Table F-1 
Task File Switch Defaults 



Switch Category: Task file 
Switch Word: $DFSWT 
Initial Contents: 
Switch Settings: 



Initial Initial 

Bit State Condition 



15 





11 





4 





3 






/-XT Not abort after n diagnostics 

/-SQ Not sequential PSECT allocation 

/-FU Not full overlay tree search 
/RO Recognize memory-resident overlay 
operator . 

/- JD; Not ixa^x D^space 



Switch Category: Task file 
Switch Word: $DFTSK 
Initial Contents: 100002 
Switch Settings: 



Initial Initial 

Bit State Condition 



15 1 /-CP, /-AL Not checkpointable! 

14 /-FP Not Floating Point Processor 

13 /-EA Not Extended Arithmetic Element 

1. The combination of not checkpointable with checkpoint 
allocation (100000) is illogical and should not be used. 

(continued on next page) 
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Table F-1 (Cont.) 
Task File Switch Defaults 



Switch Settings: (Cont.) 



Initial Initial 

Bit State Condition 



12 





11 





10 





9 





8 





7 





6 





5 





4 





2 





1 


1 









/HD Header 

/-CM Not compatibility mode 

/-DA No debugging aid 

/-PI Not position independent 

/-PR Not privileged 

/-TR No trace 

/-PM No Postmortem Dump 

/-SL Not slave task 

/SE Send to task allowed 

/-AC Not ancillary control processor 

/-AL No checkpoint allocation 

/XH External header 



Switch Category: Task File 
Switch Word: $DFTSO 
Initial Contents: 000010 
Switch Settings: 



Initial Initial 

Bit State Condition 



8 /-XH No external header 
3 1 /-SG RO and RW PSECTs 
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Table F-2 
Map File Switch Defaults 



Switch Category: Map file 
Switch Word: $DFLBS 
Initial Contents: 120000 
Switch Settings: 



Initial Initial 

Bit State Condition 



15 1 /-MA Do not include system library and STB 

files in map 



Switch Category: Map file 
Switch Word: $DFMAP 
Initial Contents: 2040 
Switch Settings: 



Initial Initial 
Bit State Condition 



10 


1 


8 





6 





5 


1 



/SH Short map 
/SP Spool 
/-CR No CREF 
/WI Wide format 



Table F-3 
Symbol Table File Switch Defaults 



Switch Category: Symbol table file 
Switch Word: $DFSTB 
Initial Contents: 
Switch Settings: 



Initial Initial 

Bit State Condition 



12 /HD Build task with header 
9 /-PI Task is not position independent 
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Table F-4 
Input File Switch Defaults 



Switch Category: Input file 
Switch Word: $DFINP 
Initial Contents: 000100 
Switch Settings: 



Bit 



Initial 
State 



Initial 
Condition 



15 
6 



/MA Include file contents in map 

/CC File contains two or more concatenated 
object modules 



F.3 THE SLOW TASK BUILDER 

TKB.TSK uses a symbol table structure that can be searched quickly, 

but which requires more work file space than that of previous 

versions. You may thus receive the following message in some 
instances: 



NO VIRTUAL MEMORY STORAGE AVAILABLE 

If this occurs, you should try to reduce the wo 
the procedures described in Section F.l. If 
sufficiently reduce the work file size, you can 
of TKB, the Slow Task Builder. This version 
but runs considerably slower than the other ver 
is STKBLD.CMD, which resides on the same devi 
Task Builder command files. The default name 
Task Builder, is ...TKB. It may be conveni 
Task Builder with a different name if you wa 
Builders in your system. 



rk file size by using 
these procedures do not 
link another version 
requires less storage, 
sions. The build file 
ce and UFD as the other 
of STK.TSK, the Slow 
ent to install the Slow 
nt to use both Task 
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THE FAST TASK BDILDER 

The Fast Task Builder (FTB) allows you to build simple tasks about 
four times faster than the Task Builder (TKB) . However, FTB has 
limited functionality. It can only link single-segment, nonprivileged 
tasks, and supports a limited number of switches and options. 

The (FTB) is intended for use as a load-and-go type of linker. It 
contains very few options and does not support: 

• New map format 

• Overlaid programs 

• FORTRAN virtual arrays 

• Production of symbol table files 

• Creation of resident libraries 

• Privileged tasks 

• Cluster libraries 

The only supported switches are: 

• /SP on map file (default = /SP) 

• /CP on task file (default = /CP) ^ 

• /EA on task file (default = /-EA) 

• /MM on task file (default = /MM) 

• /FP on task file (default = /FP) 

• /DA on input or task image (default = /-DA) 

• /LB on an input file in the form: 

>TKB TASK=PROG. OBJ, LIBRARY/LB 
but not in the form: 

>TBK TASK=PROG. OB J, LIBRARY/LB: MODULE 



1. No checkpoint space is allocated in the task image file. 
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The supported option inputs are: 

• ASG (same defaults as TKB) 

• STACK (same default as TKB) 

• UNITS 

• TASK (same default as TKB) 

• EXTSCT 

• ACTFIL (same default as TKB) 

• MAXBUF (same default as TKB) 

• LIBR 

• COMMON 

• RESLIB (same defaults as TKB) 

• RESCOM (same defaults as TKB) 

• SUPLIB 

• RESSUP (same defaults as TKB) 

FTB supports linking to shared regions but not building a shared 

region. FTB cannot link to clustered libraries. Though FTB can link 

to supervisor-mode libraries, it cannot link to overlaid 
supervisor-mode libraries. 

FTB allocates symbol table space from the end of its image to the end 

of the partition. It does not have a virtual symbol table. An Extend 

Task or equivalent of 8K is recommended. FTB does not dynamically 
extend itself at run time. 

FTB runs approximately four times faster than TKB on an 11/70 with 
RP04S when TKB is running with a totally resident symbol table. In 
smaller systems with slower disks, the ratio should be much higher. 

FTB also supports shared regions. 

FTB uses asynchronous system traps (ASTs) and therefore requires AST 
support in the Executive. 
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ERROR MESSAGES 



The Task Builder (TKB) produces diagnostic and fatal error 
Error messages are printed in the following forms: 

TKB — *DIAG*-error-message 

or 



messages , 



TKB — *FATAL*-error-message 

Some errors are correctable when command input is from a terminal. In 
such a case, a diagnostic error message can be printed, the error 
corrected, and the task-building sequence continued. However, if the 
same error is detected in an indirect command file, a correction 
cannot be made and the Task Builder aborts. 



Some diagnostic 
condition. If 



error messages merely advise you of an unusual 
you consider the condition normal for your task, you 
can install and run the task image. 



NOTE 

The Task Builder exits with two 
statuses: it returns an ERROR status 
when it encounters a diagnostic error, 
and a SEVERE ERROR when it encounters a 
fatal error. (For more information 
about the Exit-With-Status directive, 
see the RSX-llM/M-PLUS Executive 
Reference Manual.) 



This appendix tabulates the error messages produced by TKB. Most of 
the messages are self-explanatory. In some cases, the line in which 
the error occurred is printed. 

A Software Performance Report (SPR) should be submitted to DIGITAL in 
cases where the explanation accompanying a message refers to a system 
error. 

Allocation failure on file file-name 

TKB could not acquire sufficient disk space to store the task 
image file, or did not have write-aecess to the UFD or volume 
that was to contain the file. 
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Blank P-section name is illegal 
overlay-description-line 

The overlay-description-line printed contains a .PSECT directive 
that does not have a p-section name. 

Cluster library element library-name does not have nail root 

This is a fatal error. All libraries, except the first, must be 

PLAS-overlaid and have a null root. The first library in the 

group can be nonoverlaid or overlaid with a null or non-null 
root . 

Command I/O error 

An I/O error occurs on a command input device. (Device may not 
be on line, or possible hardware error.) 

Command syntax error 

command -line 

The command-line printed has incorrect syntax. 

Complex relocation error - divide by zero: module 

module -name 

A divisor having the value was detected in a complex 
expression. The result of the divide was set to 0. (Probable 
cause: division by a global symbol whose value is undefined.) 

Conflicting base addresses in cluster library 

This conflict arises when you specify APRs, for both PIC and 
non-PIC libraries that are included in the cluster. See the APR 
parameter as described in the CLSTR option. This is a fatal 
error. 

Disk image core allocation too large 
invalid-line 

The minimum disk allocation specified in the invalid line is 
greater than 128. 

File file-name attempted to store data in virtual section 

The file contains a module that has attempted to initialize a 
virtual section with data. 

File file-name has illegal format 

The file file-name contains an object module whose format is not 
valid. 

Illegal APR reservation 

An APR specified in a COMMON, LIBR, RESCOM, or RESLIB keyword is 
outside the range 0-7. 

Illegal cluster configuration 

If the cluster contains a non-overlaid library, that library must 
be the first library in the cluster. Check the configuration of 
the libraries in the cluster. This is a fatal error. 
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Illegal default priority specified 

option-line 

The option-line printed contains a priority greater than 250. 

Illegal device/volume 

invalid-line 

The invalid line printed contains an illegal device 
specification. 

Illegal directory 
invalid-line 

The invalid line printed contains an illegal directory name. 

Illegal error-severity code octal-list 

System error (no recovery) . An SPR should be submitted with a 
copy of the message containing the octal-list as printed. 

Illegal filename 
invalid-line 

The invalid-line printed contains a wildcard (*) in a file 
specification. Using wildcards is prohibited. 

Illegal get command line error code 

System error (no recovery) . 

Illegal logical unit number 

invalid-line 

The invalid-line printed contains a device assignment to a unit 
number larger than the number of logical units specified by the 
UNITS keyword, or assumed by default if the UNITS keyword is not 
used. 

Illegal multiple parameter sets 
invalid-line 

The invalid-line printed contains multiple sets of parameters for 
a keyword that allows only a single parameter set. 

Illegal number of logical units 

invalid-line 

The invalid-line printed contains a logical unit number greater 
than 250. 

Illegal ODT or task vector size 

ODT or SST vector size specified is greater than 32 words. 

Illegal overlay description operator 

invalid-line 

The invalid-line printed contains an unrecognizable operator in 
an overlay description. This error occurs if the first character 
in a p-section or segment name is a dot (.). 
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Illegal overlay directive 

invalid-line 

The invalid-line printed contains an unrecognizable overlay 
directive. 

Illegal partition/common block specified 
invalid-line 

User-defined base or length is not on a 32-word boundary. 

Illegal P-sect ion/segment attribute 

invalid-line 

The invalid-line printed contains a program section or segment 
attribute that is not recognized. 

Illegal reference to library P-section p-sect-name 

A task has attempted to reference a p-sect-name existing in a 
shared region but has not named the shared region in a keyword. 
This error occurs when you explicitly specify an STB file as an 
input file, but you have not specified the library to which the 
STB file belongs in an option. 

Illegal switch 

file-specification 

The file-specification printed contains an illegal switch or 
switch value. 

Incompatible reference to library P-section p-sect-name 

A task has attempted to reference more storage in a shared region 
than exists in the shared region definition. 

Incorrect library module specification 

invalid-line 

The invalid-line contains a module name with a non-Radix-50 
character. 

Indirect command syntax error 

invalid-line 

The invalid-line printed contains a syntactically incorrect 
indirect file specification. 

Indirect file depth exceeded 

invalid-line 

The invalid-line printed gives the file reference that exceeded 
the permissible indirect file depth (2) . 

Indirect file open failure 
invalid-line 

The invalid-line contains a reference to a command input file 
that could not be located. 
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Insufficient parameters 

invalid-line 

The invalid-line contains a keyword with an insufficient number 
of parameters to complete its meaning. 

Invalid APR reservation 

invalid-line 

APR is specified on a keyword for an absolute library. 

Invalid keyword identifier 

invalid-line 

The invalid-line printed contains an unrecognizable keyword. 

Invalid partition/common block specified 

invalid-line 

A partition is invalid for one of the following reasons: 

• TKB cannot find the partition name in the host system in order 
to get the base and length. 

• The system is mapped, but the base address of the partition is 
not on a 4K boundary for a nonrunnable task or is not for a 
runnable task. 

• The memory bounds for the partition overlap a shared region. 

• The partition name is identical to the name of a previously 
defined COMMON or LIBR shared region. 

• The top address of the partition for a runnable task exceeds 
32K minus 32 words for a mapped system, or exceeds 28K minus 1 
for an unmapped system. 

• A system-controlled partition was specified for an unmapped 
system. 

Invalid reference to mapped array by module module-name 

The module has attempted to initialize the mapped array with 
data. An SPR should be submitted if DIGITAL-supplied software 
caused this problem. 

Invalid window block specification 

invalid-line 

The number of extra address windows specified exceeds the number 
permitted. On an RSX-llMsjystem, you can specify as many as 7 
extra window blocks; , on all RSX-llM-PLIJS system," you can . specify, 
as many as 15 extra window blocksV 

If you build a task on an RSX-llM system and specify more window 
blocks, you get this error message, but the task will build. 
However, it cannot be installed and run on an RSX-llM system. 

I/O error library image file 

An I/O error has occurred during an attempt to open or read the 
Task Image File of a shared region. 
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I/O error on input file file- 



name 



This error occurs when TKB cannot read an input file 
specification (for example, when the command line is greater than 
80 characters) . 

I/O error on output file file-name 

Label or name is multiply defined 

invalid-line 

The invalid-line printed defines a name that has already appeared 
as a .FCTR, .NAME, or .PSECT directive. 

Library file filename has incorrect format 

A module has been requested from a library file that has an empty 
module name table. 

Library not built as a supervisor mode library 

The library referred to in a RESSUP or SUPLIB opt > ^ii u i". Ijiiilt 
witnout a completion (CMPRT=X) routine .ud ^n n'lt a 
supervisor-mode library. 

Library library-name not found in any cluster 

All task image and symbol table files to be included as cluster 
elements must reside in LB: [1,1]. 

Library references overlaid library 

invalid-line 

An attempt was made to link the resident library being built to a 
shared region that has memory-resident overlays. 

Load addr out of range in module module-name 

An attempt has been made to store data in the task image outside 
the address limits of the segment. This problem is usually 
caused by one of the following: 

• An attempt to initialize a p-section contained in a shared 
region 

• An attempt to initialize an absolute location outside the 
limits of the segment or in the task header 



9 



A patch outside the limits of the segment to which it applies 
An attempt to initialize a segment having the tlODSK attribute 



Lookup failure on file file name 
invalid-line 

The invalid-line printed contains a file name that cannot be 
located in the directory. 

Lookup failure on system library file 

TKB cannot find the system Library (SYO: [1,1]SYSLIB.0LB) file to 
resolve undefined symbols. 
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Lookup failure resident library file - filename. ext 

No symbol table or task image file can be found for the shared 
region "filename. ext ." If the shared region was linked to another 
shared region, ensure that the task image of both regions and the 
symbol table files exist on the same device and in the same UIC 
as the UIC referenced by the option RESLIB, RESCOM, LIBR, COMMON, 
jRBSSUP, or SOPLIB. 

Module module-name ambiguously defines P-section p-sect-name 

The p-section p-sect-name has been defined in two modules not on 
a common path, and referenced from a segment that is common to 
both paths . 

Module module-name ambiguously defines symbol sym-name 

Module module-name references or defines a sym.bol sym.-name whose 
definition exists on two different paths, but is referenced from 
a segment that is common to both paths. 



Module module-name contains incompatible autoload vectors 

You are trying to build an I- and D-space task and link it to an 
older existing library that contains an old-style vector format. 
Rebuild the library with the RSX-llM-PLUS Version 2.1 or later 
version Task Builder to create new-style vectors foe the library. 
Then rebuild your task. 

Module module-name illegally defines xfr address p-sect-name addr 

This message occurs under any one of the following conditions: 

• The start address printed is odd. 

• The module module-name is in an overlay segment and has a 
start address. The start address must be in the root segment 
of the main tree. 

• The address is in a p-section that has not yet been defined. 
An SPR should be submitted DIGITAL-supplied software caused 
this problem. 

Module module-name multiply defines P-section p-sect-name 

• The p-section p-sect-name has been defined more than once in 
the same segment with different attributes. 

• A global p-section has been defined more than once with 
different attributes in more than one segment along a common 
path. 

Module module-name multiply defines symbol sym-name 

Two definitions for the relocatable symbol sym-name have occurred 
on a common path. Or two definitions for an absolute symbol with 
the same name but different values have occurred. 

Module module-name multiply defines xfr addr in seg 

segment-name 

This error occurs when more than one module making up the root 
has a start address. 
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Module module-name not in library 

TKB could not find the module named on the LB switch in the 
library. 

No dynamic storage available 

TKB needs additional symbol table storage and cannot obtain it. 
(If possible, install TKB in a larger partition.) 

No memory available for library library-name 

TKB could not find enough free virtual memory to map the 
specified shared region. 

No root segment specified 

The overlay description did not contain a .ROOT directive. 

No virtual memory storage available 

Maximum permissible size of the work file is exceeded. The user 
should consult Appendix F for suggestions on reducing the size of 
the work file. 

Open failure on file file-name 

Option syntax error 

invalid-line 

The invalid-line printed contains unrecognizable syntax. 

Overlay directive has no operands 

invalid-line 

All overlay directives except .END require operands. 

Overlay directive syntax error 

invalid-line 

The invalid-line printed contains a syntax error or references a 
line that contains an error. 

Partition partition-name has illegal memory limits 

• The partition-name defined in the host system has a base 
address alignment that is not compatible with the target 
system. 

• The user has attempted to build a privileged task in a 
partition whose length exceeds the task's available address 
space (8K or 12K) . 

Pass control stack overflow at segment segment-name 

System error. An SPR should be submitted with a copy of the ODL 
file associated with the error. 

PIC libraries may not reference other libraries 

invalid-line 

The user has attempted to build a position-independent shared 
region that references another shared region. 
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P-section p-sect-name has overflowed 

A section greater than 32K has been created. 
Required input file missing 

At least one input file is required for a task build. 

Required partition not specified 

The PAR keyword was not used when running TKB on an RSX-llD host 
system. The keyword must contain explicit base address and 
length specifications. 

Resident library has incorrect address alignment 

invalid-line 

The invalid-line specifies a shared region that has one of the 
following problems: 

• The library references another library with invalid address 
bounds (that is, not on 4K boundary in a mapped system) . 

• The library has invalid address bounds. 

Resident library mapped array allocation too large 

invalid-line 

The invalid-line printed contains a reference to a shared region 
that has allocated too much memory in the task's mapped array 
area. The total allocation exceeds 2.2 million bytes. 

Resident library memory allocation conflict 

keyword -St ring 

One of the following problems has occurred: 

• More than seven shared regions have been specified. 

• A shared region has been specified more than once. 

• Non-position-independent shared regions whose memory 
allocations overlap have been specified. 

Root segment is multiply defined 
invalid-line 

The invalid-line printed contains the second .ROOT directive 
encountered. Only one .ROOT directive is allowed. 

Segment seg-name has addr overflow: allocation deleted 

Within a segment, the program has attempted to allocate more than 
32,764 words {32K-1 words). A map file is produced, but no task 
image file is produced. 

Segment seg-name not found for patch 

The Task Builder could not locate the named segment for a global 
patch. The option used was GBLPAT=X: Y:0, 
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Supervisor mode completion routine is undefined 

TKB could not locate the symbol X, which was specified in the 
CMPKT=X option. 

Symbol sym-name not found for patch 

TKB could not locate symbol Y for a global patch. The option 
used was GBLPAT=X: Y:0. 

Task has illegal memory limits 

An attempt has been made to build a task whose size exceeds the 
partition boundary. If a task image file was produced, it should 
be deleted. 

Task has illegal physical memory limits 

mapped-array task-image task extension 

The sum of the parameters displayed — mapped array size, task 
image size, and task extension — exceeds 2.2 million bytes. The 
quantities are shown as octal numbers in units of 64-byte blocks. 
Any resulting task image file should be deleted. 

Task image file filename is noncontiguous 

Insufficient contiguous disk space was available to contain the 
task image. A noncontiguous file was created. After deleting 
unnecessary files, the /CO switch in PIP should be used to create 
a contiguous copy. 

Task requires too many window blocks 

The number of address windows required by the task and any shared 
regions exceeds 8 for RSX-llM tasks and 16 for RSX-llM-PLOS 
tasks . 

Task-build aborted via request 

option-line 

The option-line contains a request from the user to abort the 
task build. 

Too many nested .ROOT/.FCTR directives 

invalid-line 

The invalid-line printed contains a .FCTR directive that exceeds 
the maximum nesting level (16) . 

Too many parameters 

invalid-line 

The invalid-line printed contains a keyword with more parameters 
than required. 

Too many parentheses levels 

invalid-line 

The invalid-line printed contains a parenthesis that exceeds the 
maximum nesting level (16) . 



H-10 



ERROR MESSAGES 

Truncation error in module module-name 

An attempt has been made to load a global value greater than +127 
or less than -128 into a byte. The low-order eight bits are 
loaded . 

Unable to open work file 

The work file device is not mounted. (The work file is usually 
located on the same device as is the Task Builder.) 

Onbalanced parentheses 

invalid-line 

The invalid-line printed contains unbalanced parentheses, 
n Undefined symbols segment seg-name 

The segment named contains n undefined symbols. If no memory 
allocation file is requested, the symbols are printed on the 
terminal. 

Virtual section has illegal address limits 

option-line 

The option-line printed contains a VSECT keyword whose base 
address plus window size exceeds 177777. 

Work file I/O error 

An I/O error occurs during an attempt to reference data stored by 
TKB in its work file. 
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ABSOLUTE SHARED REGION 

A shared region that has the same virtual addresses in all tasks 
that refer to it= 

AUTOLOAD 

The method of loading overlay segments, in which the Overlay 
Run-Time routines automatically load overlay segments when they 
are needed and handles any unsuccessful load requests. 

AUTOLOAD VECTOR 

A transfer of control instruction generated by the Task Builder 
to resolve an up-tree reference to a global symbol. 

CO-TREE 

One of one or more secondary tree structures within a multiple 
tree overlay structure. When a co-tree's root segment contains 
code or data, the root segment of the co-tree is made resident in 
physical memory through calls to the Overlay Run-Time routines. 

COMMON BLOCK 

Another name for resident common. 
DISK-RESIDENT 

That which resides on disk storage until needed. 

DISK-RESIDENT OVERLAY SEGMENT 

An overlay segment that shares the same physical memory and 
virtual address space with other segments. The segment is read 
in from disk each time it is loaded (compare Memory-Resident 
Overlay Segment) . 

GLOBAL CROSS-REFERENCE 

A list of global symbols, in alphabetical order, accompanied by 
the name of each referencing module. 

GLOBAL SYMBOL 

A symbol whose definition is known outside the defining module. 

HEADER 

That portion of a task image that contains the task's 
characteristics and status. Shared regions, although built like 
a task, do not have a header. 
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HOST SYSTEM 

The system on which a task is built. 
LOGICAL ADDRESSES 

The actual physical addresses that the task can access. 

LOGICAL ADDRESS SPACE 

The total amount of physical memory to which the task has access 
rights. 

MAIN TREE 

An overlay tree whose root segment is loaded by the Executive 
when the task is made active. 

MANUAL LOAD 

The method of loading overlay segments in which the user includes 
explicit calls in his routines to load overlays and handles 
unsuccessful load requests. 

MAPPED ARRAY AREA 

An area of the task's physical memory, preceding the task image, 
that is used for storage of large arrays. Space in the area is 
reserved by means of the VSECT keyword or through a Mapped Array 
Declaration contained in an object module. Access is through the 
mapping directives issued at run time. 

MEMORY ALLOCATION FILE 

The output file created by the Task Builder that lists 
information about the size and location of components within a 
task . 

MEMORY-RESIDENT 

In general, that which resides in memory all the time. The 
entity, as in the case of memory-resident overlays, may initially 
reside on disk. 

MEMORY-RESIDENT OVERLAY SEGMENT 

An overlay segment that shares virtual address space with other 
segments, but which resides in its own physical memory. The 
segment is loaded from disk only the first time it is referenced; 
thereafter, mapping directives are issued in place of disk load 
requests. 

OVERLAY DESCRIPTION LANGUAGE 

A language that allows you to describe the overlay structure of a 
task. 
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OVERLAY RUNTIME ROUTINES 

A set of system library subroutines linked as part of an overlaid 
task that are called to load segments into memory. 

OVERLAY SEGMENT 

A segment that shares virtual address space with other segments, 
and is loaded when needed. 

OVERLAY TREE 

A tree structure consisting of a root segment and optionally one 
or more overlay segments. 

PATH 

A route that is traced from one segment in the overlay tree to 
another segment in that tree. . 

PATH -DOWN 

A path toward the root of the tree. 

PATH-LOADING 

The technique used by the autoload method to load all segments on 
the path between a calling segment and a called segment. 

PATH-UP 

A path away from the root of the tree. 

PHYSICAL ADDRESS 

The assigned byte location in physical memory, which is usually 
located in the processing unit. 

POSITION-INDEPENDENT REGION 

A shared region that can be placed anywhere in a referencing 
task's virtual address space when the system on which the task 
ruiis has memory management hardware. 

PRIVILEGED TASK 

A task that has privileged memory access rights. A privileged 
task can access the Executive and the I/O page in addition to its 
own partition and referenced shared regions. 

PROGRAM SECTION 

A section of memory that is a unit of the total allocation. A 
source program is translated into object modules that consist of 
program sections with attributes describing access, allocation, 
relocatability, and so forth. 



REGION 



A contiguous block of physical addresses in which a driver, a 
task, a resident common, or library resides. 
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RESIDENT COMMON 

A shared region in which data resides that can be shared by two 
or more tasks. 

RESIDENT LIBRARY 

A shared region in which single copies of commonly used 
subroutines reside that can be shared by two or more tasks. 

ROOT SEGMENT 

The segment of an overlay tree that, once loaded, remains in 
memory during the execution of the task. 

RUNNABLE TASK 

A task that has a header and stack and that can be installed and 
executed. 

SHARED REGION 

A shared region is a block of data or code that resides in 
physical memory and can be used by any number of tasks. A shared 
region is built and installed separately from the task. 

SUPERVI SO'K-MODE< I^IBRiARY 

A liferary 'of routines that ...uses the supervisor-mode memory 
management a'pRs to map to both tiie task and itk own routines.; 

SYMBOL DEFINITION FILE 

The output object file created by the Task Builder that contains 
the global symbol definitions and values and sometimes program 
section names, attributes, and allocations in a format suitable 
for reprocessing by the Task Builder. Symbol definition files 
contain linkage information about shared regions. 

TARGET SYSTEM 

The system on which a task executes. 

TASK IMAGE FILE 

The output file created by the Task Builder that contains the 
executable portion of the task. 

VIRTUAL ADDRESSES 

The addresses within the task. Task addresses can range from 
zero through 177777(8) depending on the length of the task. 

VIRTUAL ADDRESS SPACE 

That space encompassed by the range of virtual addresses that the 
task uses. 

VIRTUAL PROGRAM SECTION 

A program section that has virtual memory allocated to it, but 
not physical memory. Virtual address space is mapped into 
physical memory at run-time by means of the mapping directives. 
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WINDOW 



A continuous virtual address space that can be moved to allow the 
task to examine different parts of a region or different regions. 



WINDOW BLOCK 



A structure defined by the Task Builder that describes a range of 
continuous virtual addresses. 
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Abort 
TKB 

during input, 11-4 
ABORT option, 11-4 
Absolute region 

See Region 
ABSPAT option, 11-5 
/AC switch, 10-5 
Access-code, 2-4 to 2-5 

grouping program section by, 
10-36 
ACP 

specifying APR, 10-5 
specifying task as, 10-5 
ACTFIL option, 11-6 
Active Page Register 

See APR 
Address 

assigning, 2-1 
concepts, 2-13 
logical, 2-14 
mapped system, 2-18 
physical, 2-13 

mapped system, 2-17 
space, 2-14 
virtual, 2-14 
virtual and logical 
coincidence, 2-15 
space translation, 2-23 
transfer, A-5 
virtual, 2-13 

mapped system, 2-17 to 2-18 
virtual and logical 

relationship, 2-17, 2-21 
virtual space 

co-tree and main tree, 3-40 
disk-resident overlay, 3-1 

to 3-4 
division, 2-18 
division by memory 

management, 2-18 
in overlay tree, 3-24 
memory-resident overlay, 

3-6 
overlaid task, 3-10, 3-14 
overlay, 3-5, 3-33 to 3-35 
reducing usage of, 3-1 
virtual space allocation 
diagram 
creating ODL file, 3-36 
virtual space and memory 

overlaid task, 3-11 to 3-14 
/AL switch, 10-6 
$$ALER 

reserved PSECT name, E-2 



ALERR module, 5-53 
Allocation-code, 2-4 to 2-5 
ALSCT FORTRAN subroutine, 5-56 

to 5-58 
$$ALVC 

PSECT, 7-11 

reserved PSECT name, E-2 
$$ALVD 

PSECT, 7-11 

reserved PSECT name, E-2 
$$ALVI 

PSECT, 7-11 

reserved PSECT name, E-2 
Ancillary control processor 

See ACP 
APR, 2-16 

I- and D- space 

allocation in multiuser 
task, 9-3 
relocatable region 

specifying for, 5-6 
resident common 

system-owned, 11-11 
resident library 

system-owned, 11-11 
specifying for ACP, 10-5 
supervisor-mode, 8-2 to 8-3 
Arithmetic element 
extended 

specifying, 10-16 
Array declaration 

mapped, A-10 
ASG option, 11-7 
Asterisk (*) 

See also Autoload indicator 
cross-reference 

of overlaid task, 4-13 
cross-reference listing, 
10-12 
At sign (@) 

cross-reference 

of overlaid task, 4-13 
cross-reference listing, 

10-12 to 10-13 
indirect file, 1-5 
Attribute 

in .NAME directive 
DSK, 3-28 
GBL, 3-28 
NODSK, 3-28 
NOGBL, 3-28 
program section 

restriction, 2-3 
save, 2-4 
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$$AUTO 

PSECT, 5-52 to 5-53 
reserved PSECT name, E-2 
AUTO module, 5-52 
AUTOL module, 5-52 
Autoload, 4-1 

applying indicator 

co-tree root, 4-2 

•FCTR label name, 4-3 

file name, 4-2 

portions of ODL tree, 4-2 

program section name, 4-3 

segment name, 4-3 
code sequence 

conventional task, 4-5 
error handling, 4-11 to 4-12 
indicator, 4-2 

efficiently placed, 4-6 
overhead in region, 5-13 
path loading, 4-3 to 4-4 
specifying, 4-1 
vector, 4-4 

eliminating unnecessary, 
4-6 

I- and D-space, 7-9, 7-11 

overlay, 3-20 
vector format 

conventional task, 4-4 

I- and D-space, 4-4 to 4-5 
Autoloadable 

data segment, 4-7 
making file 

using file name, 4-2 
making program section, 4-3 

.BLK 

See Program section 
Block 

label, 2-8 
Buffer record 

maximum size, 11-23 
Build file 

modifying 

to improve performance, F-1, 
F-5 

/CC switch, 10-7 
Checkpoint 
area 

in task image, B-9 
space 

allocating, 10-6, 10-10 
Checkpointable task 

specifying a, 10-6, 10-10 
Circumflex () 

cross-reference listing, 

10-12 to 10-13 
global cross-reference 

of an overlaid task, 4-13 
CLSTR option, 11-8 to 11-9 
Cluster library, 5-44 

See also Library 
/CM switch, 10-8 



$CMPAL 

completion routine, 8-8 to 
8-9 
CMPAL option, 8-9 
$CMPCS 

completion routine, 8-8 
CMPCS module, 8-9 
CMPRT option, 8-9, 11-10 

use in CSM library, 8-3, 8-8 
use in supervisor-mode 
library, 8-7 
/CO switch, 10-9 
Code 

access, 2-4 to 2-5 
allocation, 2-4 to 2-5 
relocation, 2-4 
scope, 2-4, 2-7 
type, 2-5, 2-7 
Comma ( , ) 

See ODL operator 
Command 
file 

indirect, 1-5 

interaction with indirect, 

1-5 to 1-6 
level of indirection, 1-7 
with ODL, 3-30 
line 

comments in, 1-8 

form, 1-2 

multi-line input, 1-3 

option input, 1-3 

output file interpretation, 

1-3 
terminating character, 1-3, 

1-5 to 1-6 
to build a task, 1-2 
UFD convention, 1-9 
sequence 

comments in, 1-8 
simple, 1-2 
Comment 

in command sequence, 1-8 
in line, 1-8 
Common, 5-1, 5-26 to 5-31 
See also Region 
allocation diagram, 5-20 
assigning references, 5-23 
building a linkinq task, 5-21 

to 5-22 
building and linking to, 5-14, 

5-17 to 5-18 
building and linking to a 
device, 5-26 to 5-31 
device, 5-26 to 5-31 

See also Device common 
establishing offset in, 5-28 
in MACRO-11 

building and linking to, 

5-17 to 5-18 
building and linking to a 
See Reaion 
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Common (Cont.) 

installing in RSX-llM, 5-2 to 

5-3, 5-20 
installing in RSX-llM-PLUS, 

5-2 to 5-3, 5-20 
linking to region, 5-14 
map, 5-19 
PSECT 

building a linking task, 
5-23 
region, 2-19 
resident, 5-1 to 5-2 

declaring, 11-11, 11-28 
name block data, B-8 
specifying a, 10-9 
typical, 5-2 
COMMON option, 11-11 to 11-12 
Completion routine 

$CMPAL, 8-2, 8-8 to 8-9, 8-18 

$CMPCS, 8-2, 8-8 

content of a, 8-12 to 8-14 

CSM library, 8-13 

definition, A-11 

identification, A-11 

name, A-11 

supervisor-mode library, 8-2, 

8-7 
user-written, 8-21 
Complex relocation, A-22 
entry, A-23 
operation codes, A-22 
Concatenated object module 

using to reduce overhead, F-4 
Control section 
name, a-5 
name entry, A-5 
Cotree, 3-31 
and main tree 

virtual address space, 3-40 
global symbol resolution, 

3-17 
null root, 3-31 
ODL statement 

from allocation diagram, 
3-39 to 3-40 
overlay, 3-34 to 3-35 
segment 

affecting symbol search on, 
10-19 
segment loading, 4-2 
Counter 
location 

definition, A-17 
modification, A-18 
/CP switch, 10-10 
/CR switch, 10-11 to 10-13 
Cross-reference 
global 

of overlaid task, 4-12 to 
4-14 
listing 

specifying a, 10-11 



CSM library 

completion routine, 8-12 to 

8-14 
dispatching, 8-19 
linking task 

example of, 8-9 
supervisor-mode, 8-7 
building, 8-7 to 8-8 
.STB file, 8-8 
CTRL/Z 

effect on Task Builder, 11-4 

/DA switch, 10-14 
Data 

adjacency in memory, 2-28 
segment 

autoloadable, 4-7 
structure 

building a, 2-1 
overlay of a, 3-19 
Data base 

overlay, B-15 

I- and D-space task, B-15 
Data format 
input 

Task Builder, A-1 
$$DBTS 

reserved PSECT name, E-2 
Debugging aid 

including a, 10-14 
Declaration flag byte 

symbol , A-7 
Default of switch 

modifying, F-7 to F-11 
Descriptor 
region, B-21 
segment, B-18 
window, B-20 to B-21 
Development step 

program, 1-1 
Device 

assignment, 11-7 
common, 5-29 

building and linking to a, 
5-26 to 5-31 
$$DEVT 

reserved PSECT name, E-2 
Directive 

memory management 

in mapping, 2-24 
.NAME, 3-27 
attributes for, 3-28 
example of use, 3-28 
ODL, 3-23 to 3-24 
.END, 3-23 
.FCTR, 3-25 
introduction, 3-23 
.ROOT, 3-23 
•PSECT, 3-29 

use of parentheses, 3-24 
Directory record 

declare global symbol, A-2 
end of global symbol, A-11 
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Directory record (Cont.) 

global symbol 
end of, A-11 

internal symbol, A-24 

relocation, A-12 
Disk image, 2-8 to 2-9 

conventional task, 7-5 
Disk-resident 

overlay, 3-1 to 3-2 
loading, 4-1 

overlay structure, 3-2 
Displaced relocation 

internal, A-15 
/DL switch, 10-15 
DSPPAT option, 11-13 
Dump 

See Postmortem dump 

See Snapshot dump 

memory, D-1 
Dynamic region, 2-20, 5-40 to 
5-43 

/EA switch, 10-16 
/EL switch, 10-17 
Element 

extended arithmetic 
specifying, 10-16 
.END directive, 3-23 
End of global symbol directory, 

A-11 
End of module record, A-24 
Error 

exit TKB commands on, 11-4 
handling 

$ALERR entry, 4-12 
for autoload, 4-11 to 4-12 
for manual load, 4-12 
overlay, 4-12 
message, H-1 
Exclamation point (!) 
See ODL operator 
operator 

See ODL operator 
Extend Task directive 

to improve performance, P-2 
EXTSCT option, 11-14 
EXTTSK option, 11-15 

Factor 

autoloadable 

making first component of, 
4-3 
Fast Task Builder, G-1 
speed of, G-2 
supported 

features, G-1 to G-2 
options, G-2 
switches, G-1 
unsupported features, G-1 to 
G-2 
.FCTR directive, 3-25 
argument 

library modules, 3-26 



.FCTR directive 
argument (Cont.) 
library to resolve 

references, 3-26 
named input file, 3-25 
PSECT name, 3-26 
segment name, 3-26 
arguments for, 3-25 
use of label in, 3-25 
.FCTR statement 

allocation diagram 

creating from, 3-38 to 3-39 
File 

command 

level of indirection, 1-7 
declaring number of active, 

11-6 
indirect command, 1-5 
input 

designating as debugging 

aid, 10-14 
designating as library file, 

10-23 
directing selective symbol 
search, 10-47 to 10-49 
including content of in map, 

10-26 
processing to reduce 

overhead, F-6 
specifying as default 
library, 10-15 
library 

declaring a, 10-23 
making file autoloadable 

using name, 4-2 
map 

printing, 1-2 
omitting a specific output, 

1-3 
open at one time, 11-6 
specification 

convention for, 1-8 
default for, 1-8 
Floating Point Processor 

specifying, 10-18 
FMTBUF option, 11-16 
FORTRAN 

common block 

in overlays, 3-19 
manual load calling sequence, 
4-9 to 4-10 
for I- and D-space task, 
4-11 
run-time support 

virtual program section, 
5-56 to 5-57 
/FP switch, 10-18 
$$FSR1 

reserved PSECT name, E-3 
. FSRPT 

low-memory context, B-10 
reserved global symbol, E-1 
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FTB library 

overlaid region, 5-13 
/FU switch, 10-19 

GBLDEF option, 11-17 
GBLINC option, 11-18 
GBLPAT option, 11-19 
GBLREF option, 11-20 
GBLXCL option, 11-21 

use in CSM library, 8-3, 8-7 
to 8-8, 8-18 
Global 

additive relocation, A-15 
relocation, A-15 

additive displaced, A-17 
displaced, A-16 
symbol 

address of ODT SST routine, 

11-24 
ambiguously defined in 

overlay, 3-16 - 
declaration directory 

record, A-2 
directory record format, 

A- 4 
end of directory record, 

A-11 
from the default library, 

3-18 
in autoloadable segment, 

4-4, 4-6 
in cross-reference listing, 

10-12 to 10-13 
multiplydef ined, 3-16 
multisegment task, 3-16 
name, A-6 
name entry, A-6 
overlay search sequence, 

3-17 
resolution, 2-7 
search sequence in overlays, 

3-16 
undefined, 2-7 
symbol resolution 
co-tree, 3-17 
default library, 3-18 
in multisegment task, 3-16 

/HD switch, 10-20 
Header, 2-8 

excluding task, 10-20 
I- and D-space task, 7-11 
in task image, B-10 
task 

fixed part, B-11 
variable part, B-12 
vector extension area, B-13 
High-level language 

overlay program in, 3-40 to 
3-41 
Host system, C-1 

building a task for another 
system, C-1 



Host system (Cont.) 

transferring from task, C-1 
Hyphen (-) 

See ODL operator 

I- and D-space 

specifying, 10-21 
I- and D-space task 

See Task 
I/O page 

specifying, 10-22 
/ID switch, 10-21 
Image 

disk, 2-8 to 2-9 

memory, 2-8 to 2-9 
Indirect command file, 1-5, 
3-30 

with ODL, 3-30 
Information record 

text, A-11 
Input 

data format 

Task Builder, A-1 

multi-line 

to the Task Builder, 1-3 
Internal displaced relocation, 

A-15 
Internal symbol 

directory record, A-24 

name entry, A-5 
$$1081 

reserved PSECT name, E-3 
$$I0B2 

reserved PSECT name, E-3 
/IP switch, 10-22 

Label block, 2-8 

group, B-1 
Language 
high-level 

overlay program in, 3-40 
/LB switch, 10-23 to 10-24 
LBLDF$ macro, B-1 
/LI switch, 10-25 
LIBR 

linking to region, 5-14 
option, 11-11 to 11-12 
Library 

building a, 5-14 
cluster, 5-44 

building, 5-44, 5-48 to 

5-51 
building example, 5-48 to 

5-51 
building rule 1: overlays, 

5-45 
building rule 2: references, 

5-46 
building rule 3: .STB file, 

5-47 
building rule 4: stack, 

5-47 
building rule 5: PIC, 5-47 
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Library 

cluster (Cont.) 

building rule 6: traps, 

5-47 
building rule summary, 5-44 
examples, 5-47 
overlay run-time support, 

5-51 to 5-53 
resolving interlibrary 
references, 5-49 
declaring a, 10-23 
default 

controlling symbol search, 

10-15, 10-19 
global symbol resolution, 

3-18 
specifying a, 10-15 
extending a, 10-17 
file 

declaring a, 10-23 
FTB 

overlaid region, 5-13 
linking resident to 

supervisor-mode, 8-21 
modules 

.FCTR directive, 3-26 
object module 

placing in overlay 
structure, 10-24 
old 

overlaid region, 5-13 
region, 2-20 

specifying, 10-25 
relocation 

resident, A-23 
resident, 5-1, 5-3 

building and linking to a, 

5-14, 5-31 to 5-38 
data in task image, B-4 to 

B-6 
declaring, 11-11, 11-28 
label block 0, B-7 
label block 1, B-9 
label block 2, B-9 
label block 3, B-9 
name block data , B-8 
relocation, A-23 
search, 10-23 
resolving references 

.FCTR directive, 3-26 
restriction in I- and D-space 

task, 7-9 
supervisor-mode, 2-24, 8-1 
building, 8-7 
building linking task, 8-17 

to 8-18 
building the referencing 

task, 8-7 
building with relevant 

options, 8-3, 8-7, 8-17 
to 8-18 
completion routine, 8-2, 



Library 

supervisor-mode (Cont,) 
converting SCAL to CSM, 

8-20 
data in, 8-3 
definition, 8-1 
example of, 8-10 to 8-17 
linking, 8-7 

linking a resident, 8-20 
linking to, 8-21 
linking to SYSLIB, 8-2, 8-7 

to 8-9, 8-18 
linking with relevant 

options, 8-3, 8-8, 8-18 
mapping of, 8-3 
method of mode switching, 

8-1, 8-19 
mode switching, 8-1, 8-7 
mode switching compared, 

8-1 
mode- switching vector, 8-1 
$MSDS directive, 8-2 
$MSDS directive restriction, 

8-2 
multiple, 8-20 
overlaid, 8-21 to 8-22 
overlay restriction, 8-21 

to 8-22 
parameter passing, 8-2 
restrictions on contents, 

8-2 
using as resident, 8-20 
using system supplied 

vector, 8-19 
with I- and D-space task, 

8-3 
your own completion 

routines in, 8-21 
your own vector in, 8-21 
supervisor-mode mapping 

with conventional task, 8-4 

to 8-5 
with I- and D-space task, 
8-6 
SYSLIB 

replacing as default, 10-23 
Linking 

module, 2-3 
Listing 

global cross-reference 
generating as, 10-11 
wide 

specifying a, 10-51 
$$LOAD 

PSECT, 5-53 

reserved PSECT name, E-3 
LOAD module, 5-53 
$LOAD routine 

in manual load, 4-7 
Loading 

asynchronous example of, 4-10 
mechanism 

overlay, 3-16 
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Location counter 

definition, A-17 

modification, A-18 
Logical 

address, 2-14 

address space, 2-14 

unit number 

assigning physical device 
to a, 11-7 

unit table entry, B-9 , B-14 

units 

number of, 11-39 
Low-memory context, B-10 
LUN 

See Logical unit number 

/MA switch, 10-26 
Macro 

SNAP$, D-6 
SNPBK$, D-6 
SNPDF$, D-5 
MACRO-11 calling sequence 
manual load, 4-7 

1- and D-space tasks, 4-8 
to 4-9 
Manual load 

calling sequence, 4-7 to 4-8 
error handling, 4-12 
FORTRAN calling sequence, 4-9 
to 4-10 
for I- and D-space task, 
4-11 
MACRO-11 calling sequence, 
4-7 
I- and D-space tasks, 4-8 
to 4-9 
Map 

common, 5-19 
file 

adding cross-reference to a, 

10-11 
content, 10-37 to 10-43 
description, 10-37 to 10-43 
example, 10-37 to 10-43 
general, 10-37 to 10-43 
inhibiting spooling of a, 

10-45 
printing, 1-2 
specifying, 10-26 
including SYSLIB contribution, 

10-26 
multiuser task, 9-7 
overlaid I- and D-space task, 

7-12 to 7-16 
privileged task, 6-10 to 6-11 
region, 5-19 
resident region 

includinq symbol definition, 
10-26 
short 

specifying a, 10-37 to 

spooling to print, 10-45 



Map (Cont.) 
task 

I- and D-space, 7-9 
linked to a common, 5-24 
Mapped 
array 

area, 5-56, 5-58 
declaration, A-10 
declaration entry, A-10 
region 

declaring address window, 
11-41 
system, 2-14, 2-18 
Mapping 

concept, 2-22 
conventional task 

supervisor-mode library, 
2-26 to 2-27 
conventional task linked to 
region 
I- and D-space system, 7-3 
I- and D-space task, 7-3 to 
7-4 
in I- and D-space system, 
7-4 
in supervisor-mode, 2-24 
task, 2-15 
MAXBUF option, 11-23 
.MBLUN 

reserved global symbol, E-1 
Memory 

allocation 

I- and D-space task, 7-9 
allocation file 

See Map file 
dump, D-1 
image, 2-8 to 2-9 
layout 

unmapped system, 2-16 
management 

specifying for target 
system, 10-27 
physical 

disk-resident overlay, 3-3 

to 3-4 
memory-resident overlay, 

3-6 
overlay, 3-5, 3-33 to 3-35 
reducing to build a task, F-4 
reducing usage of, 3-1 
resident overlay structure, 

3-6 
saving 

overlaid task, 3-9 to 3-10 
virtual allocation 

I- and D-space task, 7-10 
Memory management 

use by task, 2-15 to 2-16 
Memory Management Unit, 2-14 
Memory- resident 
overlay 

loading, 4-1 
overlay, 3-1 
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Message 

diagnostic 

eliminating, 10-30 
error, H-1 

virtual memory system, F-5 
inhibiting system queuing of, 
10-35 
/MM switch, 10-27 
Mode 

compatibility 
in a task, 10-8 
Mode-switching 

to supervisor-mode, 8-8, 8-12 

to 8-13 
vector 

supervisor library, 8-1, 
8-19 
Module 

extracting from library, 

10-23 
linking, 2-3 
name, A-4 

name entry format, A-4 
object 

extracting by name, F-4 
linking, 2-1 
placing in segment 

reducing overhead, F-4 
record 

end of, A-24 
.MOLUN 

reserved global symbol, E-1 
/MP switch, 10-28 
$$MRKS 

PSECT, 5-52 

reserved PSECT name, E-3 
/MU switch, 10-29 
Multi-line input, 1-3 
Multiple-tree 
example, 3-32 
structure, 3-31 to 3-32 
defining a, 3-31 to 3-32 
Multisegment task 

See Overlay 
Multiuser task, 2-28, 9-1 
as an overlaid task, 9-2 
building a, 9-5 
declaring read-only partition 

for, 11-33 
defined, 9-1 
disk image, 9-2 
example, 9-6 to 9-7 
example map, 9-7 
I- and D-space, 9-3 
APR allocation, 9-3 
PSECT allocation, 9-4 
PSECT in, 9-3 
windows, 9-5 
program section allocation, 

9-1 to 9-2 
specifying a, 10-29 
TKB command sequence, 9-7 



Multiuser task (Cont.) 

window block assignment, 9-1, 
9-3 

N . OVPT 

low-memory context, B-10 
reserved global symbol, E-1 
Name 

global symbol, A-6 
.NAME directive, 3-27 
attribute 
DSK, 3-28 
GBL, 3-28 
NODSK, 3-28 
NOGBL, 3-28 
example of use of, 3-28 
.NLUNS 

reserved global symbol, E-1 
/NM switch, 10-30 
.NOVLY 

reserved global symbol, E-1 
.NSTBL 

reserved global symbol, E-1 
Null 

root, 3-31 

in ODL, 3-31 
segment 

in ODL, 3-31 
Number sign (#) 

in cross-reference listing, 
10-12 to 10-13 

$$0BF1 

reserved PSECT name, E-3 
$$0BF2 

reserved PSECT name, E-3 
Object code 

patching, 11-5 
Object module 

concatenating, 10-7 

content of, A-1 

format, A-3 

linking, 2-1 

overriding definition in, 

11-17 
relocatable, 2-2 
selective global symbol 

using /SS to include, 10-47 
to 10-49 
Object Time System 

usage to extend record buffer, 
11-16 
ODL 

autoload indicator, 4-2 
directive, 3-23 to 3-24 
.END, 3-23 

example use of .NAME, 3-28 
.FCTR, 3-25 
introduction, 3-23 
.NAME, 3-27 

.NAME attributes, 3-28 
.PSECT, 3-29 
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ODL (Cont.) 

efficiently placing in 

autoload indicator, 4-6 
enabling operator 

memory-resident overlay, 
10-34 
file 

declaring a, 10-28 
multiple-tree 

defining structure, 3-30 

example, 3-31 to 3-32 

structure, 3-30 
operator 

, (comma) , 3-24 

! (exclamation point) , 3-24, 
3-26 to 3-27 

- (hyphen) , 3-24 
introduction, 3-24 

summary, 3-49 to 3-52 
using indirect file with, 
3-30 
ODL file 
creating 

start of procedure, 3-36 
with allocation diagram, 
3-35 to 3-36 
.FCTR Statement 

creating from allocation 
diagram, 3-38 to 3-39 
.ROOT statement 

creating from allocation 
diagram, 3-37 
virtual address space 

in allocation diagram, 3-36 
ODL statement 
co-tree 

from allocation diagram, 
3-39 to 3-40 
ODT vector, 11-24 
.ODTLl 

reserved global symbol, E-1 
.0DTL2 

reserved global symbol, E-1 
ODTV option, 11-24 
Operator 
ODL, 3-24 

, (comma) , 3-24 
! (exclamation point), 3-24, 
3-26 to 3-27 

- (hyphen) , 3-24 
introduction, 3-24 

Option 

category of, 11-1 
general form of, 1-4 
input 

in command line, 1-3 
linking to region, 5-14 
separation of argument list, 

1-4 to 1-5 
summary, 11-2 
Task Builder, 1-4, 11-1 

ABORT, 11-4 

ABSPAT, 11-5 



Option 

Task Builder (Cont.) 
ACTFIL, 11-6 
ASG, 11-7 

CLSTR, 11-8 to 11-9 
CMPRT, 11-10 
COMMON or LIBR, 11-11 to 

11-12 
DSPPAT, 11-13 
EXTSCT, 11-14 
EXTTSK, 11-15 
FMTBUF, 11-16 
GBLDEF, 11-17 
GBLINC, 11-18 
GBLPAT, 11-19 
GBLREF, 11-20 
GBLXCL, 11-21 
MAXBUF, 11-23 
ODTV, 11-24 
PAR, 11-25 to 11-26 
PRI, 11-27 
RESCOM or RESLIB, 11-28 to 

11-29 
RESSUP, 11-31 to 11-32 
ROPAR, 11-33 
STACK, 11-34 
SUPLIB, 11-35 
TASK, 11-36 
TSKV, 11-37 
UIC, 11-38 
UNITS, 11-39 
VSECT, 11-40 
WNDWS, 11-41 
Option summary, 11-3 
OTS 

usage to extend record buffer, 
11-16 
$OTSV 

low-memory context, B-10 
reserved global symbol, E-2 
Output files 

omitting specific, 1-3 
OVCTC module, 5-52 
OVCTL module, 5-52 
OVCTR module, 5-52 
OVDAT module, 5-53 
$$OVDT 

PSECT, 5-53 

reserved PSECT name, E-3 
Overlay, 2-10 

allocation diagram 

creating ODL file with, 

3-35 to 3-40 

autoload vector in, 3-20 

building an, 3-41 to 3-48 

building memory-resident 

for region, 5-9 
capability of an, 3-1 
choosing a memory-resident, 

3-14 
co-tree, 3-34 to 3-35 

d_j U — — _ T^ TC 
ax-a uaae f d— j.o 

I- and D-space task, B-16 



Index-9 



INDEX 



Overlay (Cont.) 

data structure, 3-19 

linked into root, 3-20 
defining a multiple- tree, 

3-31 to 3-32 
description 

effect on performance, F-4 
disk-resident, 3-1 to 3-2 

defined, 4-1 
effect of 

on physical memory, 3-5 
on virtual address space, 
3-5 
effect of virtual address 
space 
on disk-resident, 3-1 to 
3-4 
effect on memory 

of a disk-resident, 3-2 
of disk-resident, 3-1, 3-3 
to 3-4 
effect on physical memory 
of memory-resident, 3-6 
effect on virtual address 
space 
of a memory-resident, 3-6 
error handling, 4-12 
example of building a, 3-41 

to 3-48 
I- and D-space task 

disk image, 7-8 
in I- and D-space task, 3-21, 
7-5 
PSECT, 7-6 
loading 

asynchronously, 4-10 
disk-resident, 4-1 
mechanism, 3-16 
memory-resident, 4-1 
methods, 4-1 

synchronously, 4-8 to 4-9 
memory-resident, 3-1, 3-6 
conserving physical memory, 

3-14 
defined, 4-1 

physical memory usage, 3-6 
region, 5-9 

virtual address space, 3-14 
multiuser task, 9-2 
of program 

in high-level language, 
3-40 to 3-41 
operator 

enabling recognition of, 

10-34 
suppression of a 

memory-resident, 10-34 
path loading in an, 4-4 
physical memory, 3-33 to 3-35 
program section 

specifying, 3-19 
region 

autoload vector* 5—11 



Overlay 

region (Cont.) 
building, 5-9 
building option, 5-10 to 

5-11 
descriptor in, 3-20 
example of building, 5-10 
global symbols in .STB file, 

5-11 
resolving symbol, 5-10 to 

5-11 
.STB file, 5-11 
vectors in I- and D-space 
task, 5-11 
region restrictions, 5-12 
root segment structure, 3-21 
run-time, 3-19 

comparison of sizes in 

routine, 4-16 
module sizes, 5-52 to 5-53 
routine, 3-19, 4-16 
size of routine, 4-16 
support requirements, 5-12, 

5-51 to 5-53 
use of routine, 4-14 to 
4-15 
segment 

alignment, 10-8 
arrangement, 3-15 
descriptor in, 3-20 
processing order, 3-17 
symbol processing, 3-17 
structure 

considerations in creating, 

3-1 
most effective, 3-2 
multiple-tree, 3-18 
multiply defined global 

symbol, 3-16 
specifying library search 
in a, 10-23 
task, 3-7, 3-9 

global cross-reference of, 

4-12 to 4-14 
segment calls, 3-10 
virtual address space, 3-10 
tree, 3-15 

calling segments in an, 4-6 
virtual 

address space, 3-33 to 3-35 
address space and memory, 
3-11 to 3-14 
window 

block, 3-49 
descriptor in, 3-20 
written in high-level 

language, 3-40 to 3-41 
Overlay Description Language 

introduction, 3-15 
Overlay Description Operator 

See ODL 
Overlay structure 
global symbol 
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Overlay structure 

global symbol (Cont.) 

ambiguously defined, 3-16 
Overlay tree 

for I- and D-space task, 7-7 
Overlay tree diagram 

virtual address space, 3-24 
OVIDC module, 5-52 
OVIDL module, 5-52 
OVIDR module, 5-52 
$$OVRS 

reserved PSECT name, E-3 

Page Address Register 

See PAR 
Page Description Register 

See PDR 
PAR, 2-16 

option, 11-25 
PAR option, 11-26 

building region, 5-2 
Parentheses 

use of 

in ODL, 3-24 
Partition 

declaring, 11-25 

in region, 5-28 

naming for target system, C-1 

option, 11-25 

requirement 

shared region, 5-3 

requirements 
region, 5-2 

size 

for TKB, F-2 

specifying for region, 5-28 
Patch 

D-space, 11-13 

declaring an object level, 
11-5 

global relative, 11-19 
Path loading, 4-3 to 4-4 

See also Overlays 

example of, 4-4 

in autoload, 4-3 to 4-4 
$$PDLS 

PSECT, 5-52 

reserved PSECT name, E-3 
PDR, 2-16 
Performance 

improving TKB, F-1 
Physical 

address, 2-13 

mapped system, 2-17 
/PI switch, 10-31 
/PM switch, 10-32 
PMD task 

installation for timely 
operation, D-1 
Postmortem dump, D-1 

content, D-3 to D-5 

example, D-2 

sample, D-3 to D-5 



Postmortem dump (Cont.) 

specifying a, 10-32 
/PR switch, 6-2, 10-33 
/PR:0 privileged task, 6-2, 6-4 

to 6-5 
/PR:0 privileged task, uses of, 

6-5 
/PR:4 privileged task, 6-2, 6-4 

to 6-5 
/PR:4 privileged task, uses of, 

6-5 
/PR:5 privileged task, 6-2, 6-4 

to' 6-6 
/PR:5 privileged task, uses of, 

6-5 
PRI option, 11-27 
Priority 
task 

declaring, 11-27 
Privileged and nonprivileged 
task 
distinction between, 6-1 
Privileged task, 2-25, 6-1 
accessing 

Executive with a, 6-4 
I/O page with a, 6-4 
building a, 6-6 to 6-11 
comparison of nonprivileged 

and, 6-1 
hazards of a, 6-1 to 6-2 
in a mapped system, 6-1 
logging off from, 6-1 
MAC command sequence, 6-9 
map of, 6-10 to 6-11 
mapping of, 6-2 to 6-3 
/PR:0, 6-2, 6-4 to 6-5 
/PR: 4, 6-2, 6-4 to 6-5 
/PR:5, 6-2, 6-4 to 6-6 
processor trap in a, 6-2 
specifying, 2-25 
specifying a, 6-2 
TKB command sequence, 6-10 
to examine unit control block, 
6-6 to 6-11 
Program 

development step, 1-1 
limit, A-18 
section, 5-53 

additive displaced 

relocation, A-21 
additive relocation, A-20 
adjacency requirement for, 

10-46 
allocation, 2-2 
attribute, 2-4 
attribute restriction, 2-3 
blank (.BLK) , 2-3 
creation, 2-3 

displaced relocation, A-19 
element, 2-2 
extension of, 11-14 
in shared region, 5-7 
making autoloadable, 4-3 
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Program 

section (Cont.) 
name, 2-3 
name conflict, 5-7, 5-39 to 

5-40 
naming restriction, 5-7 
ordering, 5-7, 10-36, 10-46 
overlay allocation, 3-19 
relocation, A-19 
resolution of, 3-19 
resolving names, 5-7, 5-39 

to 5-40 
resolving names in region 

and task, 5-16 
save attribute, 2-7 
segregating, 10-36, 10-46 
sequential ordering of, 

10-36, 10-46 
space allocation, 2-5 to 

2-6 
specifying explicitly in 

overlay, 3-29 
specifying in overlay, 3-19 
virtual, 5-53 
section name, A-7 

applying autoload indicator, 
4-3 
section name entry, A-8 
section name flag byte, A-8 

to A-9 
version 

identification, A-10 
Program section 
$$ALVC, 7-11 
$$ALVD, 7-11 
$$ALVI, 7-11 
I- and D-space task 

overlay, 7-6 
multiuser task 

I- and D-space, 9-3 
named 

in region, 5-13 
virtual 

allocating physical memory 

to a, 5-56 
attaching virtual attribute 

to a, 5-56 
building a task using, 5-58 

to 5-61 
creating a, 5-56, 5-58 to 

5-61 
FORTRAN run-time support 

for, 5-56 to 5-57 
option usage, 5-55 
specifying, 11-40 
specifying base address for 

a, 5-56 
specifying length, 5-54 
specifying physical size, 

5-54 
specifying window size, 

5-54 
support for a, 5-56 to 5-57 



PSECT 

See also Program section 

See Program section 
.PSECT directive, 3-29 
PSECT name 

.FCTR directive 
argument, 3-26 
.PTLUN 

reserved global symbol, E-2 

$$RDSG 

PSECT, 5-52 

reserved PSECT name, E-3 
Region, 2-18 
absolute, 5-9 

building precautions, 5-7 
mapping for, 5-8 
mapping of, 5-7 
specifying an, 5-7 
symbol definition file, 5-9 
allocation 

diagram, 5-20 
of window block for, 5-25 
APR 

specifying, 5-6 
assigning references, 5-23 
building 

a linking task, 5-21 to 

5-22 
and linking to a, 5-14, 

5-17 to 5-18 
interaction of /CO/LI/PI 

switch, 5-3 
options 

in an overlaid, 5-10 
options in an overlaid, 

5-11 
use of /CC/LI/PI switch, 

5-3 
with PAR option, 5-2 
common, 2-19 to 2-20 
descriptor, B-21 
descriptor in overlay, 3-20 
dynamic, 2-20, 5-40 to 5-43 
building a task that 

creates a, 5-40 to 5-43 
installing in RSX-llM, 5-2 to 

5-3, 5-20 
installing in RSX-llM-PLUS, 

5-2 to 5-3, 5-20 
library, 2-20 
linked to a region, 5-26 
linked with a region, 5-25 
linking to a, 5-13 to 5-14, 

5-26 
map, 5-19 

mapping of an absolute, 5-7 
memory-resident overlaid, 5-9 
building, 5-9 
example of building, 5-10 
number of, 5-17 
options for building p 5-17 to 
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Region (Cont.) 

options for linking to, 5-14 
overlaid, 5-9 

autoload call overhead, 

5-13 
autoload in, 5-13 
autoload vector, 5-11 
FTB and old libraries, 5-13 
global symbols in .STB file, 

5-11 
I- and D-space task vectors, 

5-11 
named program section, 5-13 
run- time support for, 5-12 

to 5-13 
.STB file, 5-11 
partition, 5-28 

requirements, 5-2 
procedure for building a, 

5-17 to 5-18 _ 
program section in, 5-7 
PSECT 

building a linking task, 
5-23 
relocatable, 5-5 
mapping, 5-5 
specifying, 5-5 
specifying APR for, 5-6 
.STB file for a, 5-9, 5-14, 
5-16 
resident relocatable, 5-5 
resolving PSECT names, 5-39 

to 5-40 
shared, 2-20, 5-1 

allocation of window block 

for, 5-14 
autoload vectors in, 5-12 
defined, 5-1 
initializing window block 

for, 5-14 
installing, 5-16 
partition requirement, 5-3 
resolving PSECT names, 5-16 
restrictions for overlaid, 

5-12 
symbol definition file, 

5-16 
use of /CO/LI/PI switches, 

5-9 
windows in, 5-14 
size of, 5-17 
specifying 

as position independent, 

10-9, 10-31 
partition for, 5-28 
.STB file, 5-4 to 5-5, 5-14, 
5-16 
for an absolute, 5-7, 5-9, 

5-12 
using /CO/LI/PI switches, 

symbol definition file, 5-9 
task, 2-18 to 2-20 



Region (Cont.) 

task building options, 5-13 

to 5-14 
type of access to, 5-14 
use of /CO/LI/PI switches, 

5-5 
window, 5-15, 5-25 
with linked task 

in I- and D-space system, 
7-3 
Relocatable region 

See Region 
Relocation 
code, 2-4 
complex, A-22 
entry, A-23 
operation codes, A-22 
directory command byte, A-13 
directory record, A-12 
entries, A-12 to A-13 
format, A-14 
displaced 

global, A-15 
global, A-15 

additive, A-16 
global additive displaced, 

A-17 
internal, A-14 

displaced, A-15 
library 

resident, A-23 
program section, A-19 
additive, A-20 
additive displaced, A-21 
displaced, A-19 
resident library,. A-23 
RESCOM 

linking to region, 5-14 
option, 11-28 to 11-29 
Reserved symbol 

for the Task Builder, E-1 
Resident 
common 

name block data, B-8 
library 

name block data, B-8 
relocation, A-23 
memory 

for TKB performance, F-3 
overlay operator 

enabling recognition of, 
10-34 
region 

using to reduce overhead, 
F-4 
Resident region 
map file 

including symbol definition 
in, 10-26 
RESLIB 

linkinq to region, 5-14 
option', 11-28 to 11-29 
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RESLIB 

option (Cont.) 

in supervisor-mode library, 
8-20 to 8-21 
RESSUP 

option, 8-9, 11-31 to 11-32 
use in CSM library, 8-3, 

8-8, 8-19 to 8-21 
use in supervisor-mode 
library, 8-7 
Restarting TKB option, 11-4 
$$RGDS 

reserved PSECT name, E-3 
RLSCT FORTRAN subroutine, 5-56, 

5-58 
/RO switch, 10-34 
Root 

in a co-tree, 3-31 
null, 3-31 

in ODL, 3-31 
structure 

overlay, 3-21 
•ROOT directive, 3-23 
.ROOT statement 

allocation diagram 
creating from, 3-37 
ROPAR option, 11-33 
$$RTQ 

PSECT, 5-52 to 5-53 
reserved PSECT name, E-3 
$$RTR 

PSECT, 5-52 to 5-53 
reserved PSECT name, E-4 
$$RTS 

PSECT, 5-53 

reserved PSECT name, E-4 
Run-time support 

overlaid region, 5-12 to 5-13 
autoload, 5-13 
autoload call overhead, 

5-13 
FTB and old libraries, 5-13 
named program sections, 
5-13 

Save attribute, 2-4 
SCAL to CSM library 

converting, 8-20 
Scope-code, 2-4, 2-7 
/SE switch, 10-35 
Segment 

autoloadable 
data, 4-7 

global symbol in, 4-4 
call, 3-10 

to up-tree, 4-6 
definition of a, 3-1 
descriptor, B-19 

I- and D-space task, 7-11 
in overlay, 3-20 
limiting number 

reducing overhead. F-4 
loading 



Segment 

loading (Cont.) 

as part of co-tree, 4-2 
when called, 4-4, 4-6 
making autoloadable, 4-3 
mapping, 2-10 

disk-resident, 2-11 
memory-resident, 2-12 
multiple, 3-5 

global symbol in, 3-16 
global symbol resolution, 

3-17 
symbol resolution, 3-16 
name 

applying autoload indicator 

to, 4-3 
.FCTR directive argument, 
3-26 
null 

in ODL, 3-31 
overlay 

arrangement, 3-15 
root structure, 3-21 
symbol processing, 3-17 
processing order, 3-17 
single, 3-4, 3-8 
up-tree 

I- and D-space, 3-22 
Semicolon (; ) , 1-8 
SEND directive 

enabling for your task, 10-35 
/SG switch, 10-36 
$$SGD0 

PSECT, 5-53 

reserved PSECT name, E-4 
$$SGD1 

reserved PSECT name, E-4 
$$SGD2 

PSECT, 5-53 

reserved PSECT name, E-4 
/SH switch, 10-37 
Shared region, 5-1 

See Region 
Single segment task, 3-8 
/SL switch, 10-44 
Slash 

double (//) , 1-6 
single (/) , 1-5 to 1-6 
Slow TKB 

to improve overhead, F-11 
$$SLVC 

reserved PSECT name, E-4 
SNAP$ macro, D-6 
format of, D-8 
Snapshot dump, D-5 to D-6 
example of, D-10 to D-12 
format of macro for creating, 
D-7 
SNPBK$ macro, D-6 

format of, D-7 
SNPDF$ macro, D-6 
/SP switch, 10-45 
/SQ switch, 10-46 
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/SS switch 

symbol definition file 
reducing overhead, F-4 
SST vector address 
declaring, 11-27 
Stack 

declaring size, 11-34 
supervisor-mode, 8-20 
STACK option, 11-34 
•STB file, 5-9 

absolute region, 5-7, 5-9 
content of a, 5-5 
excluding symbol from, 5-11 
for region, 5-4 to 5-5, 5-14, 

5-16 
I- and D-space task, 7-9 
including symbol in, 5-11 
interaction of /CO/LI/PI 

switches, 5-4 
overlaid region, 5-11 to 5-12 

global symbols in, 5-11 
program sections, 5-16 
program sections in, 5-5 
relocatable region, 5-9, 5-16 
use of /CO/LI/PI switches, 
5-5, 5-9 
Structure 
in TKB 

size of, F-3 
,SUML1 

reserved global symbol, E-2 
Supervisor-mode, 2-24 
library, 2-24 
See Library 
mapping, 2-24, 2-26 to 2-27 
mode switching, 8-8, 8-12 to 

8-13 
stack, 8-20 
SUPLIB 

option, 8-9, 11-35 

use in CSM library, 8-3, 

8-19 
use in supervisor-mode 
library, 8-7 
Switch 

conflict in, 10-1 
default 

modifying, F-7 to F-11 
modifying default of, F-7 to 

F-11 
summary, 10-2 to 10-4 
syntax, 10-1 
Task Builder, 10-1 
/AC[:n] , 10-5 
/AL, 10-6 
/CC, 10-7 
/CM, 10-8 
/CO, 10-9 
/CP, 10-10 
/CR, 10-11 to 10-13 

/TMi in 1 A 

/DL, 10-15 
/EA, 10-16 



Switch 

Task Builder (Cont.) 
/EL, 10-17 
/FP, 10-18 
/FU, 10-19 
/HD, 10-20 
/ID, 10-21 
/IP, 10-22 
/LB, 10-23 to 10-24 
/LI, 10-25 
/MA, 10-26 
/MM, 10-27 
/MP, 10-28 
/MU, 10-29 
/NM, 10-30 
/PI, 10-31 
/PM, 10-32 
/PR[:n] , 10-33 
/RO, 10-34 
/SE, 10-35 
/SG, 10-36 
/SH, 10-37 
/SL, 10-44 
/SP, 10-45 
/SQ, 10-46 
/SS, 10-47 to 10-49 
/TR, 10-50 
/WI, 10-51 
/XH, 10-52 
/XT[:n] , 10-53 
Symbol 

affecting search for, 2-7 
declaration flag byte, A-7 
definition file 

excluding symbol from a, 

11-21 
for system-owned region, 

11-11 
for user-owned region, 

11-29 
including symbols, 11-18 
reducing overhead, F-4 
directory record 

declare global, A-2 
end of global, A-11 
internal, A-24 
full search in overlays 

specifying, 10-19 
global 

address of ODT SST routine, 

11-24 
ambiguously defined in 

overlay, 3-16 
declaring definition in a 

task, 11-17 
default library resolution, 

3-18 
directory record, A-2 
directory record format, 

A-4 

A-11 
excluding in a task, 11-21 
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Symbol 

global (Cont.) 

from the default library, 

3-18 
in autoloadable segment, 

4-4, 4-6 
in cross-reference listing, 

10-12 to 10-13 
including in a task, 11-18 
multiplydefined, 3-16 
multisegment task, 3-16 
name, A-6 
name entry, A-6 
overlaid region .STB file, 

5-11 
overlay search sequence, 

3-17 
resolution, 2-7, 3-17 
resolution in co-tree, 3-17 
resolution in multisegment 

task, 3-16 
undefined, 2-7 
in cross-reference listing, 

10-12 
internal 

autoloadable library, A-26 

to A-27 
end-of-module, A-30 
end-of-module format, A-32 
global, A-28 

internal symbol name, A-30 
internal symbol name format, 

A-31 
line-number, A-29 to A-30 
literal record, A-30 
literal record format, A-31 
module name, A-27 to A-28 
overall format, A-24 to 

A-25 
PC correlation, A-29 to 

A-30 
PSECT item, A-29 
relocatable/relocated, A-27 
start-of-segment, A-25 to 

A-26 
task identification, A-26 
TKB generated, A-25 
name entry 

internal, A-5 
number of processed for 

performance, F-3 
reserved for the Task Builder, 

E-1 
resolving 

overlay region, 5-11 
search 

selective, 10-47 to 10-49 
Symbol definition 
SYSLIB.OLB, 2-7 
Symbol definition file 
See also .STB file 
supervisor-mode library 
system-owned, 11-35 



Symbol definition file 
supervisor-mode library 
(Cont.) 
user-owned, 11-31 
Syntax rule 

summary of, 1-10 
SYSLIB 

including contribution in map, 

10-26 
linking to 

by supervisor-mode 

libraries, 8-2, 8-7 to 
8-9, 8-18 
replacing as default, 10-23 
SYSLIB.OLB 

for symbol definition, 2-7 
System 

host and target, C-1 
mapped, 2-14 

physical and virtual space, 
2-15 
object module library, 2-2 
See also Library 
See also SYSLIB.OLB 
target 

memory management, 10-27 
unmapped, 2-14 
System-controlled partition 
extending memory for task in, 
11-15 

T-bit trace trap, 10-50 
Table storage, F-2 
memory for 

to improve performance, F-2 
Target system, C-1 

transfering task to a, C-1 
Task 
access 

system-owned common or 

library, 11-11 
system-owned 

supervisor-mode library, 
11-35 
user-owned common, 11-28 
user-owned library, 11-28 
user-owned supervisor-mode 
library, 11-31 
active files 

declaring number of, 11-6 
additional memory for, 11-15 
address windows 

declaring an additional, 
11-41 
ancillary control processor 

specifying as, 10-5 
assigning physical device to 

LUN, 11-7 
attaching slave attribute to, 

10-44 
building for target system, 

C-1 
changing name of, 11-36 
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Task (Cont.) 

checkpointable 

specifying, 10-10 
command line to build a, 1-2 
comparison 

conventional and I- and 
D-space, 7-2 
completion routine for a, 

11-10 
conventional 

autoload vector, B-17 
disk image, 7-6 
mapping compared to I- and 
D-space task, 7-2 
creating a dynamic region, 

5-40 
creating multiuser, 10-29 
D-space 

overlay structure, 3-21 
data 

in task image, B-4 to B-6 
needed by system to install, 
B-1 
declaring 

execution priority for, 

11-27 
maximum stack size of, 

11-34 
number of LUNs for, 11-39 
object-level patch for, 

11-5 
ODT SST vector in, 11-24 
disk image, 2-8 
enabling 

postmortem Dump for, 10-32 
T-bit trace trapping in, 
10-50 
extending 

a program section in a, 

11-14 
memory of, 11-15 
to partition length, 11-15 
external header 

specifying, 10-52 
floating point processor in 

specifying, 10-18 
format buffer 

declaring length of, 11-16 
global relative patch 

declaring, 11-19 
global symbol 

excluding a, 11-21 
including in, 11-18 
global symbol definition 

declaring a, 11-17 
global symbol reference 

declaring a, 11-20 
header, 2-8 

allocating additional 

(checkpoint) space in, 
10-6 
checkpoint area within, B-9 



Task 

header (Cont.) 

controlling creation of, 

10-20 
fixed part, B-11 to B-12 
I- and D-space, 7-11 
space for EAE context, 

10-16 
space for floating-point 
context, 10-18 
host to target system 

example of transferring, 
C-2 
I- and D-space, 2-28, 7-1 
autoload vector, 7-9, B-17 

to B-18 
differing from conventional 

task, 2-28 
manual load calling 

sequence, 4-8 to 4-9, 
4-11 
map, 7-9 
mapped in I- and D-space 

system, 7-4 
mapping, 7-3 
mapping summary of, 7-2 
memory allocation, 7-9 
overlaid, 7-5 

overlay region vector, 5-11 
overlay structure, 3-21 
patching, 11-13 
PSECT in overlay, 7-6 
simplified mapping, 2-29 
specifying, 10-21 
.STB file, 7-9 
with up-tree segment, 3-22 
I-and-D and conventional 

mapping compared, 7-2 
identi f ication 

for I- and D-space, 7-1 
identifying partition for, 

11-25 
image, B-1, B-14 

file structure, B-1 
image on disk 

non-overlaid, B-2 
non-overlaid as Ikinked to 

library, B-2 
overlaid, B-3 
overlaid I- and D-space, 
B-4 
including debugging aid (ODT) 

in, 10-14 
inhibiting queuing message to, 

10-35 
installed name 

declaring, 11-35 
label block, 2-8 
label block 0, B-7 
label block 1, B-9 

label block 3, B-9 
linking 
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Task 

linking (Cont.) 

to a supervisor-mode 

library, 8-10 to 8-12 
to region, 5-13 
to region in I- and D-space 

system, 7-3 
to several libraries, 11-8 
to 11-9 
list of attributes, 10-37 
logical units 

number of, 11-39 
making checkpointable, 10-6 
map 

linked to a common, 5-24 
mapping, 2-15, 2-20 
maximum record buffer size 

declaring, 11-23 
memory, 2-10 
memory-resident overlay 
operator 
enabling, 10-34 
memory-resident overlay 
segment 
changing alignment of, 10-8 
multisegment, 3-5 

global symbol resolution, 
3-17 
multiuser, 2-28 

See Multiuser task 
declaring read-only 

partition, 11-33 
specifying a, 10-29 
ODT vector, 11-24 
overlaid, 3-7, 3-9 

global cross-reference of, 

4-12 to 4-14 
memory savings, 3-9 to 3-10 
segment calls, 3-10 
virtual address space, 3-10 
overlaid \- and D-space 
disk image, 7-8 
map, 7-12 to 7-16 
tree, 7-7 

virtual address, 7-7 
overlay, 2-10 
partition 

declaring, 11-25 
patching of 

with object code, 11-5 
privileged, 2-25 

See Privileged task 
specifying, 2-25 
specifying a, 10-33 
privileged access right for 

establishing, 10-33 
program section order 

effect in creating, 10-36, 
10-46 
region, 2-18 to 2-20 
relocation of, 2-2 

system-owned, 11-11 



Task (Cont.) 

resident library 

system-owned, 11-11 
single segment, 3-4, 3-8 
slave 

specifying a, 10-44 
specifications 

multiple, 1-5 
specifying 

data space in an I- and 

D-space, 7-5 

KEll-A in, 10-16 

SST vector address 

declaring, 11-37 

stack size 

declaring, 11-34 
structure, 2-8 

label block, 2-8 
supervisor-mode library for a, 

11-31, 11-35 
system mapping status of 

indicating, 10-26 
time-based schedule request 

declaring UIC for, 11-38 
traceable 

specifying a, 10-50 
UIC 

declaring, 11-38 
use of memory management, 

2-15 to 2-16 
user 

data space definition, 7-1 
vector address 

declaring system SST trap, 
11-37 
virtual program section 

specifying, 11-40 
window, 2-20 to 2-22 
in I- and D-space, 7-5 
linking to region, 5-15 
Task Builder 

command line, 1-2 
fast 

See Fast Task Builder 
function, 2-1 
option, 1-4 
switch, 10-1 
TASK option, 11-36 
Text information record, A-11 
to A-12 
format, A-12 
Throughput 

improving TKB, F-1 
TKB 
slow 

to improve performance, 
F-11 
/TR switch, 10-50 
Transfer 

address, A-6 
address entry, A-6 
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Tree 

applying autoload indicator, 

4-2 
calling segments in, 4-6 
calling up-tree segments, 4-6 
multiple 

defined, 3-30 
defining, 3-31 
structure, 3-18, 3-32 
.TRLUN 

reserved global symbol, E-2 
$$TSKP 

reserved PSECT name, E-4 
TSKV option, 11-37 
Type-code, 2-5, 2-7 

UFD conventions in command line, 

1-9 
UIC 

declaring in task, 11-38 

option, 11-38 
UNITS option, 11-39 
Unmapped 

system, 2-14 

memory layout, 2-16 
Unnamed program section 

See Program section 
.USLUl 

reserved global symbol, E-2 
.USLU2 

reserved global symbol, E-2 

Vector 

autoload, 3-20, 4-4 

conventional task, B-17 
eliminating unnecessary, 

4-6 
I- and D-space, 7-11 
I- and D-space format, 4-5 
I- and D-space task, 7-9, 

B-17 
in region, 5-12 
in task header 

extension area format, B-13 



Vector (Cont.) 
mode- switching 

supervisor library, 8-19 
supervisor-mode library, 
8-1 
ODT, 11-24 
overlaid region, 5-11 

I- and D-space task, 5-11 
SST address, 11-27 
$VEXT 

low-memory context, B-10 
reserved global symbol, E-2 
VSECT option, 11-40 

/WI switch, 10-51 
Window, 2-20 to 2-22 
block, 2-20 to 2-22 
creating a, 5-14 
for a region, 5-14 
in overlay, 3-49 
definition block, 2-22 
descriptor, B-20 to B-21 

in overlay, 3-20 
for region and linking task, 

5-15 
in I- and D-space task, 7-5 
option, 11-41 
region, 5-25 
wrap around 

in virtual sections, 5-54 
$$WNDS 

reserved PSECT name, E-4 
WNDWS option, 11-41 
Work file 
accesses 

system overhead, F-2 , F-5 
to F-7 
parameters for, F-2 
performance 

changing device to improve, 
F-5 

/XH switch, 10-52 
/XT switch, 10-53 
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